---
title: Getting Started
description: Build a complete service with Sunbeam G2V — from an empty directory to a running server and frontend.
updated_at: "2026-07-28"
---
# Getting Started
This guide walks you through building a service with the Sunbeam G2V framework — from an empty directory to a running, traced server.
## Prerequisites
- [Rust](https://rustup.rs/)
- [Docker](https://www.docker.com/) (optional, for Postgres / NATS / the OTel collector)
## 1. Create a new Rust binary
```bash
cargo new my-service --bin
cd my-service
```
## 2. Add the dependency
```bash
cargo add sunbeam-g2v
```
Or with only the features you need:
```toml
[dependencies]
sunbeam-g2v = { version = "0.6", default-features = false, features = ["axum", "metrics", "tracing", "logging"] }
tokio = { version = "1", features = ["full"] }
```
## 3. Write the service
```rust
use sunbeam_g2v::prelude::*;
use sunbeam_g2v::health::HealthRouter;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
// One-time setup for the tracing subscriber + OTel exporter. Without
// OTEL_EXPORTER_OTLP_ENDPOINT, spans are created but not exported.
let _telemetry = sunbeam_g2v::telemetry::init(Default::default())?;
let router = ServiceRouter::new();
let server = ServerBuilder::new()
.with_router(router)
.with_health(HealthRouter::new())
.build_axum()?;
server.serve().await
}
```
## 4. Run it
```bash
cargo run
# Listening on 0.0.0.0:8080
```
Test the health endpoint — note the echoed request id:
```bash
curl -i http://localhost:8080/health/live
# HTTP/1.1 200 OK
# x-request-id: 81c3c6ed-fe49-4da4-ac92-b84bffaa9f1c
```
## 5. Enable tracing
Every request already runs inside an OpenTelemetry server span; exporting
them is one environment variable away:
```bash
# Any OTLP/HTTP collector works, e.g. the contrib distro:
docker run --rm -p 4318:4318 otel/opentelemetry-collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 cargo run
```
- `x-request-id` is honored when supplied, generated otherwise, echoed on
every response, and recorded as a span attribute.
- Incoming `traceparent` headers are picked up, so traces from frontends or
upstream services connect end-to-end.
- Outbound calls made with the framework's `client` stack inject both
headers automatically.
Tune with `OTEL_SERVICE_NAME` and `OTEL_TRACES_SAMPLER_ARG` (0.0–1.0), or
build a `TelemetryConfig` explicitly.
## Next Steps
- Add authentication and permissions — see `src/middleware/auth/`
- Wire Postgres (`sqlx-postgres` feature)
- Add NATS messaging (`nats` feature)
- Run the full example: `cargo run --example simple`