Struct TelemetryBuilder 

pub struct TelemetryBuilder { /* private fields */ }

Builder for configuring telemetry options incrementally.

Created via Telemetry::builder or Telemetry::from_env. Call .init() to consume the builder and start telemetry.

Example

use std::time::Duration;

let _handles = otel_bootstrap::Telemetry::builder("my-service")
    .with_version("1.2.3")
    .with_environment("staging")
    .with_metrics(true)
    .with_shutdown_timeout(Duration::from_secs(10))
    .init()
    .unwrap();

Implementations

impl TelemetryBuilder

pub fn with_version(self, version: &str) -> Self

Set the service version (maps to service.version resource attribute).

pub fn with_environment(self, environment: &str) -> Self

Set the deployment environment (maps to deployment.environment.name).

pub fn with_sampler(self, sampler: TraceSampler) -> Self

Set an explicit trace sampler. If not set, falls back to OTEL_TRACES_SAMPLER env var, then always-on.

pub fn with_metrics(self, enabled: bool) -> Self

Enable or disable metrics export (default: true).

pub fn with_protocol(self, protocol: ExportProtocol) -> Self

Set the export protocol explicitly. If not set, falls back to OTEL_EXPORTER_OTLP_PROTOCOL, then the compiled-in default (grpc when the grpc feature is enabled, http/protobuf otherwise).

pub fn with_max_export_batch_size(self, size: usize) -> Self

Set the maximum number of spans exported in a single batch (default: 512).

Overrides OTEL_BSP_MAX_EXPORT_BATCH_SIZE when set programmatically. The env var is still read as a fallback when this method is not called.

pub fn with_metric_export_interval(self, interval: Duration) -> Self

Set the interval between metric exports (default: 60 s).

Returns an error at build time if interval is zero. Overrides OTEL_METRIC_EXPORT_INTERVAL when set programmatically.

pub fn with_logs(self, enabled: bool) -> Self

Enable or disable log export via the OTLP log bridge (default: false).

When enabled, tracing events are forwarded to an OTLP LogExporter in addition to the existing stdout fmt layer. This allows structured logs to be correlated with traces in backends like Grafana Loki or Datadog.

pub fn with_export_timeout(self, timeout: Duration) -> Self

Set the OTLP export timeout explicitly. If not set, falls back to OTEL_EXPORTER_OTLP_TIMEOUT (in milliseconds), then the SDK default of 10 000 ms.

pub fn with_shutdown_timeout(self, timeout: Duration) -> Self

Set the maximum time to wait for provider shutdown when the TelemetryHandles is dropped (default: 5 s).

If the timeout expires a warning is logged and the drop completes without panicking. The background shutdown thread is abandoned and the providers may not have flushed all pending data.

pub fn with_meter_provider_setup<F>(self, setup: F) -> Self

where F: FnOnce(MeterProviderBuilder) -> MeterProviderBuilder + Send + Sync + 'static,

Add a custom tracing_subscriber::Layer to the subscriber stack.

Multiple layers can be added by chaining calls. Each layer is composed with the built-in EnvFilter, fmt, and OpenTelemetry layers.

Insertion order in the subscriber stack (inner → outer, i.e. first-added to last-added):

registry → custom layers → EnvFilter → fmt → OTel

Because EnvFilter is outer, it can suppress events before they reach the fmt and OTel layers; custom layers receive events independently according to their own enabled() implementation.

Example

let _handles = otel_bootstrap::Telemetry::builder("my-service")
    .with_layer(tracing_subscriber::fmt::layer().with_target(false))
    .init()?;

Customise the MeterProviderBuilder before it is built.

Runs after the built-in OTLP PeriodicReader is attached (when with_metrics is enabled) and before .build() is called. The closure is the escape hatch for everything the explicit builder methods do not cover — most importantly, installing additional [MetricReader]s like opentelemetry-prometheus alongside the OTLP push, so the same instruments fan out to multiple transports without double-counting.

May be called multiple times; closures run in registration order. Has no effect when with_metrics(false) is also set on the builder — when metrics are disabled, no MeterProvider is created at all.

MetricReader is intentionally not nameable from outside opentelemetry_sdk, so the closure form is the only way to attach readers without leaking unstable trait names through this crate’s public API.

Example

// With `opentelemetry-prometheus` in scope:
let registry = prometheus::Registry::new();
let exporter = opentelemetry_prometheus::exporter()
    .with_registry(registry.clone())
    .build()?;
let _handles = otel_bootstrap::Telemetry::builder("my-service")
    .with_meter_provider_setup(move |b| b.with_reader(exporter))
    .init()?;
// ...mount `registry` at GET /metrics in your HTTP layer.

pub fn with_layer<L>(self, layer: L) -> Self

where L: Layer<Registry> + Send + Sync + 'static,

pub fn init(self) -> Result<TelemetryHandles, Box<dyn Error>>

Consume the builder and initialise OpenTelemetry.

Installs a global tracer provider, meter provider (if enabled), and a tracing subscriber. Returns an error if any provider fails to build (e.g. unknown sampler name, zero metric interval).

Example

let handles = otel_bootstrap::Telemetry::builder("my-service")
    .with_metrics(false)
    .init()
    .expect("telemetry init failed");
handles.shutdown().ok();