opentelemetry-sdk

Official OpenTelemetry SDK implementation for collecting and processing telemetry in Rust

opentelemetry-sdk

Version: 0.31.0

The opentelemetry-sdk crate provides the official SDK implementation for OpenTelemetry in Rust. It implements the processing pipeline for traces, metrics, and logs, including batching, sampling, and resource detection.

Installation

[dependencies]
opentelemetry-sdk = "0.31"

Feature Flags

Core Features:

• trace: Trace SDK (enabled by default)
• metrics: Metrics SDK (enabled by default)
• logs: Logs SDK (enabled by default)
• internal-logs: Internal SDK logging (enabled by default)

Async Runtime Support:

• rt-tokio: Use Tokio’s multi-thread runtime
• rt-tokio-current-thread: Use Tokio’s current-thread runtime
• experimental_async_runtime: Enable async runtime trait

Advanced Features:

• jaeger_remote_sampler: Remote sampling from Jaeger
• spec_unstable_metrics_views: Metrics views (experimental)
• experimental_metrics_custom_reader: Custom metric readers
• experimental_logs_batch_log_processor_with_async_runtime: Async batch log processor

Quick Start

Tracing

use opentelemetry::trace::Tracer;
use opentelemetry_sdk::trace::SdkTracerProvider;

let exporter = /* your exporter */;
let provider = SdkTracerProvider::builder()
    .with_simple_exporter(exporter)
    .build();

let tracer = provider.tracer("my_service");

tracer.in_span("doing_work", |cx| {
    // Your traced logic here
});

provider.shutdown().expect("shutdown successful");

Metrics

use opentelemetry::metrics::MeterProvider;
use opentelemetry_sdk::metrics::SdkMeterProvider;

let exporter = /* your exporter */;
let provider = SdkMeterProvider::builder()
    .with_periodic_exporter(exporter)
    .build();

let meter = provider.meter("my_service");
let counter = meter.u64_counter("requests").build();
counter.add(1, &[]);

Logs

use opentelemetry_sdk::logs::SdkLoggerProvider;

let exporter = /* your exporter */;
let provider = SdkLoggerProvider::builder()
    .with_simple_exporter(exporter)
    .build();

Key Components

Trace SDK

trace::SdkTracerProvider · struct

Main entry point for tracing. Creates Tracer instances and manages span processors.

trace::BatchSpanProcessor · struct

Batches spans before exporting (recommended for production)

trace::SimpleSpanProcessor · struct

Exports each span immediately (useful for debugging)

trace::Sampler · enum

Controls which spans to record:

• AlwaysOn: Sample all spans
• AlwaysOff: Sample no spans
• TraceIdRatioBased: Sample based on trace ID
• ParentBased: Defer to parent span’s sampling decision

Metrics SDK

metrics::SdkMeterProvider · struct

Creates Meter instances and manages metric readers

metrics::PeriodicReader · struct

Periodically exports metrics at a fixed interval (default: 60 seconds)

metrics::ManualReader · struct

Exports metrics on-demand (useful for pull-based exporters like Prometheus)

Logs SDK

logs::SdkLoggerProvider · struct

Creates Logger instances and manages log processors

logs::BatchLogProcessor · struct

Batches log records before exporting

logs::SimpleLogProcessor · struct

Exports each log record immediately

Resource Detection

Resource · struct

Immutable set of attributes describing the entity producing telemetry

use opentelemetry_sdk::Resource;
use opentelemetry::KeyValue;

let resource = Resource::builder_empty()
    .with_service_name("my_service")
    .with_attribute(KeyValue::new("environment", "production"))
    .build();

let provider = SdkTracerProvider::builder()
    .with_resource(resource)
    .build();

Propagation

The SDK includes propagator implementations:

propagation::TraceContextPropagator · struct

W3C Trace Context propagation format

propagation::BaggagePropagator · struct

W3C Baggage propagation format

Environment Variables

The SDK respects OpenTelemetry environment variables:

General

• OTEL_SERVICE_NAME: Service name
• OTEL_RESOURCE_ATTRIBUTES: Resource attributes as key-value pairs

Trace

• OTEL_TRACES_SAMPLER: Sampler type (always_on, always_off, traceidratio, parentbased_always_on, etc.)
• OTEL_TRACES_SAMPLER_ARG: Sampler argument (e.g., ratio for traceidratio)
• OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT: Max attributes per span (default: 128)
• OTEL_SPAN_EVENT_COUNT_LIMIT: Max events per span (default: 128)
• OTEL_BSP_SCHEDULE_DELAY: Batch span processor export interval in ms (default: 5000)
• OTEL_BSP_MAX_QUEUE_SIZE: Max queue size (default: 2048)
• OTEL_BSP_MAX_EXPORT_BATCH_SIZE: Max batch size (default: 512)

Metrics

• OTEL_METRIC_EXPORT_INTERVAL: Export interval in ms (default: 60000)

Logs

• OTEL_BLRP_SCHEDULE_DELAY: Batch log processor export interval in ms (default: 1000)
• OTEL_BLRP_MAX_QUEUE_SIZE: Max queue size (default: 2048)
• OTEL_BLRP_MAX_EXPORT_BATCH_SIZE: Max batch size (default: 512)

Related Crates

• opentelemetry - Core API
• opentelemetry-otlp - OTLP exporter
• opentelemetry-stdout - Stdout exporter

Documentation

Full API Documentation

View complete API reference on docs.rs

Minimum Rust Version

MSRV: 1.75.0