Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

OTLP export and lifecycle

otel-init creates trace, metric, and log providers. Export is opt-in through an endpoint environment variable.

# Enable all configured signals.
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Signal-specific endpoints can enable only one signal or override the shared endpoint for that signal:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf

The corresponding metric and log names are OTEL_EXPORTER_OTLP_METRICS_ENDPOINT / _PROTOCOL and OTEL_EXPORTER_OTLP_LOGS_ENDPOINT / _PROTOCOL. Supported protocol values in this workspace are grpc, http/protobuf, and http/json, ignoring ASCII case but without trimming surrounding whitespace. Native exporter builders resolve the signal-specific protocol first, then OTEL_EXPORTER_OTLP_PROTOCOL, then the SDK feature default; invalid values fall through to the next source. With the enabled features, the default is http/json. For a gRPC receiver, set OTEL_EXPORTER_OTLP_PROTOCOL=grpc explicitly.

When neither the signal-specific endpoint nor the shared endpoint contains a non-blank value, that provider remains local-only. It can still create trace IDs, but it does not construct an exporter or attempt a connection to localhost:4317.

Logger always initializes trace and metric providers. It initializes the log provider only when otel_logs_enabled is true, for example with LOG_OTEL_LOGS_ENABLED=true through the env feature.

Environment variable precedence

The OTLP exporters read standard endpoint, header, and timeout variables from the process environment. The metric exporter also reads OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE (cumulative, delta, or lowmemory); when unset, the SDK default is cumulative.

Sampling, metric intervals, and resource detection use SDK defaults. Explicit resource attributes are merged after detected attributes:

SDK environment variableBehavior in this library
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGConfigured entirely by the SDK. The default is parentbased_always_on: sample root spans and honor the parent’s sampling decision for child spans. Setting only the argument does not select a sampler.
OTEL_METRIC_EXPORT_INTERVALConfigured entirely by the SDK, in milliseconds. The default is 60000 (60 seconds).
OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTESDetected by Resource::builder(). Explicit resource attributes override detected values, including service.name. With no configured service name, the SDK uses unknown_service:<executable>.
RUST_LOGRead by tracing-subscriber::EnvFilter; a missing or invalid value falls back to the configured log level.

For example:

export OTEL_SERVICE_NAME=orders-api
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1
export OTEL_METRIC_EXPORT_INTERVAL=30000

In SDK 0.33, Resource::builder() runs SdkProvidedResourceDetector, TelemetryResourceDetector, then EnvResourceDetector; later values override earlier ones. Consequently, service.name in OTEL_RESOURCE_ATTRIBUTES overrides OTEL_SERVICE_NAME when both are set. This library adds no custom service-name precedence. Logger::attributes (or LOG_ATTRIBUTES) are merged last and can override either environment setting.

An empty or invalid sampler setting is handled by the SDK, which falls back to parentbased_always_on. An empty or non-numeric metric interval uses the SDK’s 60-second default. These settings apply when providers are initialized, not dynamically. Logger::service_name and LOG_SERVICE_NAME only identify the tracer’s instrumentation scope; they do not set resource service.name.

LOG_* variables configure this library’s Logger, including console output, formatting, and file rotation. They require the env feature and Logger::from_env(None) (or init_logging_from_env(None)). The OpenTelemetry SDK does not replace this configuration layer.

Environment support does not load a .env file. The examples call dotenv::dotenv() before initialization to load that file into the process environment.

Shutdown order

Keep LoggerGuard or OtelGuard alive until application shutdown. Explicit shutdown is available when the application needs to surface provider shutdown errors:

#![allow(unused)]
fn main() {
use otel_logger::Logger;
fn run() -> anyhow::Result<()> {
let guard = Logger::new("worker").init()?;
tracing::info!("draining work");
guard.shutdown()?;
Ok(())
}
}

LoggerGuard shuts down telemetry providers before releasing its optional non-blocking file writer guard. Dropping a guard also performs cleanup, but an explicit shutdown() is the path that returns provider shutdown errors.