otel-bootstrap

One-call OpenTelemetry bootstrap for Rust services — traces, metrics, and logs over OTLP with sensible defaults.

The standard opentelemetry + opentelemetry-otlp + tracing-subscriber wiring is the same in every service. This crate does it once: call init_telemetry("my-service"), keep the handle alive, and drop it to flush.

Features

• One call to wire it all up — traces, metrics, and logs over OTLP, tracing-subscriber configured, W3C TraceContext + Baggage propagators registered.
• gRPC or HTTP/protobuf — select transport via cargo feature.
• Env-var configuration — follows the OpenTelemetry spec (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_TRACES_SAMPLER, …).
• Builder API — version, environment, sampler, custom meter setup, extra subscriber layers.
• Optional axum middleware — OtelTraceLayer for inbound HTTP trace propagation.
• Generic enduser.* span enrichment — implement EnrichSpan on your context type and plug it into SpanEnricherLayer<T> with no brefwiz dependencies required.
• Graceful shutdown — drop TelemetryHandles to flush and shut down both providers.

Quick start

[dependencies]
otel-bootstrap = "2"
tokio = { version = "1", features = ["full"] }

use otel_bootstrap::init_telemetry;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _telemetry = init_telemetry("my-service")?;

    tracing::info!("service started");
    // ... run your server ...
    Ok(())
    // _telemetry dropped here → SDK flushes and shuts down
}

For more control, use the builder:

use otel_bootstrap::Telemetry;

let _telemetry = Telemetry::builder("my-service")
    .version(env!("CARGO_PKG_VERSION"))
    .environment("production")
    .init()?;

Cargo features

At least one of grpc or http must be enabled (enforced at compile time).

Configuration

Full reference: OTEL_TRACES_SAMPLER values.

Axum middleware

otel-bootstrap = { version = "2", features = ["axum"] }

use otel_bootstrap::axum_layer;

let app = Router::new()
    .route("/", get(handler))
    .layer(axum_layer());

This layer reads the traceparent / tracestate headers, starts a server span, and propagates context to all child spans.

enduser.* span enrichment

otel-bootstrap = { version = "2", features = ["axum"] }

Implement EnrichSpan on your context type, then plug it into SpanEnricherLayer:

use otel_bootstrap::span_enrichment::{EnrichSpan, span_enricher_layer};
use tracing::Span;

#[derive(Clone)]
struct MyContext { user_id: String }

impl EnrichSpan for MyContext {
    fn enrich(&self, span: &Span) {
        span.record("enduser.id", &self.user_id.as_str());
    }
}

let app = Router::new()
    .route("/", get(handler))
    .layer(span_enricher_layer::<MyContext>());

Routes with no MyContext extension are silently skipped.

Span-field log propagation

When with_logs(true) is set, otel-bootstrap replaces the upstream log bridge with SpanAwareLogBridge. It propagates span-level attributes into every OTLP log record so that request.id, enduser.*, and http.* fields appear as Loki labels alongside the trace context.

Two propagation paths are supported:

• Tracing fields declared at span creation (info_span!("req", "request.id" = id)) — captured automatically for names in [PROPAGATED_SPAN_FIELDS].
• Post-creation attributes set via record_span_log_attr_on — use this from middleware or EnrichSpan::enrich_span for fields that arrive after span creation.

use otel_bootstrap::{span_enrichment::emit_request_id, record_span_log_attr_on};
use opentelemetry::{Key, logs::AnyValue};

// In your request handler / middleware:
emit_request_id(&request_id);  // → appears in traces + logs

// In EnrichSpan::enrich_span for enduser fields:
span.set_attribute("enduser.id", user_id.clone());
record_span_log_attr_on(span, Key::new("enduser.id"), AnyValue::String(user_id.into()));

Override the captured field set per service:

const FIELDS: &[&str] = &["request.id", "enduser.id", "tenant.id"];
let _telemetry = Telemetry::builder("my-service")
    .with_logs(true)
    .with_propagated_span_fields(FIELDS)
    .init()?;

Examples

• basic_setup — minimal init
• shutdown_handling — explicit graceful flush
• custom_config — builder API with version, environment, sampler
• axum_span_enricher — axum + generic EnrichSpan enrichment

License

MIT — see LICENSE.