Runtime configuration

Overview

OpenTelemetry Rust can be configured through:

Environment variables (runtime configuration)
Cargo feature flags (compile-time configuration)
Programmatic configuration (in code)

Environment variables

General configuration

Variable	Description	Default
`OTEL_SDK_DISABLED`	Disable the SDK	`false`
`OTEL_RESOURCE_ATTRIBUTES`	Resource attributes as key-value pairs
`OTEL_SERVICE_NAME`	Service name	`unknown_service`
`OTEL_LOG_LEVEL`	SDK log level (error, warn, info, debug, trace)	`info`

OTLP exporter configuration

Variable	Description	Default
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP endpoint URL	`http://localhost:4317`
`OTEL_EXPORTER_OTLP_PROTOCOL`	Protocol (grpc, http/protobuf, http/json)	`grpc`
`OTEL_EXPORTER_OTLP_TIMEOUT`	Export timeout in milliseconds	`10000`
`OTEL_EXPORTER_OTLP_HEADERS`	Headers as key-value pairs
`OTEL_EXPORTER_OTLP_COMPRESSION`	Compression (gzip, none)	`none`

Signal-specific endpoints

Variable	Description
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Traces endpoint
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	Metrics endpoint
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Logs endpoint
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	Traces headers
`OTEL_EXPORTER_OTLP_METRICS_HEADERS`	Metrics headers
`OTEL_EXPORTER_OTLP_LOGS_HEADERS`	Logs headers

Batch processor configuration

Spans:

Variable	Description	Default
`OTEL_BSP_MAX_QUEUE_SIZE`	Max queue size	`2048`
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	Max batch size	`512`
`OTEL_BSP_SCHEDULE_DELAY`	Export interval (ms)	`5000`
`OTEL_BSP_EXPORT_TIMEOUT`	Export timeout (ms)	`30000`

Logs:

Variable	Description	Default
`OTEL_BLRP_MAX_QUEUE_SIZE`	Max queue size	`2048`
`OTEL_BLRP_MAX_EXPORT_BATCH_SIZE`	Max batch size	`512`
`OTEL_BLRP_SCHEDULE_DELAY`	Export interval (ms)	`1000`
`OTEL_BLRP_EXPORT_TIMEOUT`	Export timeout (ms)	`30000`

Trace configuration

Variable	Description	Default
`OTEL_TRACES_SAMPLER`	Sampler type	`parentbased_always_on`
`OTEL_TRACES_SAMPLER_ARG`	Sampler argument
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`	Max attributes per span	`128`
`OTEL_SPAN_EVENT_COUNT_LIMIT`	Max events per span	`128`
`OTEL_SPAN_LINK_COUNT_LIMIT`	Max links per span	`128`
`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`	Max attribute value length	unlimited

Sampler types

always_on - Sample all spans
always_off - Sample no spans
traceidratio - Sample based on trace ID (requires OTEL_TRACES_SAMPLER_ARG = ratio)
parentbased_always_on - Use parent decision, otherwise always sample
parentbased_always_off - Use parent decision, otherwise never sample
parentbased_traceidratio - Use parent decision, otherwise ratio-based

Propagator configuration

Variable	Description	Default
`OTEL_PROPAGATORS`	Comma-separated list of propagators	`tracecontext,baggage`

Supported propagators:

tracecontext - W3C Trace Context
baggage - W3C Baggage
b3 - B3 single header
b3multi - B3 multi header
jaeger - Jaeger propagation
xray - AWS X-Ray
ottrace - OpenTracing

Feature flags

opentelemetry crate

[dependencies]
opentelemetry = { version = "0.31", features = [
    "trace",           # Tracing API
    "metrics",         # Metrics API
    "logs",            # Logs API
    "internal-logs",   # Internal SDK logging
]}

opentelemetry-sdk crate

[dependencies]
opentelemetry_sdk = { version = "0.31", features = [
    "trace",           # Tracing SDK
    "metrics",         # Metrics SDK
    "logs",            # Logs SDK
    "rt-tokio",        # Tokio runtime for batch processors
    "rt-tokio-current-thread",  # Tokio current-thread runtime
]}

Experimental features:

[dependencies]
opentelemetry_sdk = { version = "0.31", features = [
    "jaeger_remote_sampler",  # Jaeger remote sampling
    "experimental_metrics_periodicreader_with_async_runtime",
    "experimental_logs_batch_log_processor_with_async_runtime",
    "experimental_trace_batch_span_processor_with_async_runtime",
]}

opentelemetry-otlp crate

[dependencies]
opentelemetry-otlp = { version = "0.31", features = [
    "grpc-tonic",      # gRPC with tonic
    "http-proto",      # HTTP with protobuf
    "http-json",       # HTTP with JSON
    "reqwest-blocking", # Blocking reqwest client
    "reqwest-rustls",  # Reqwest with rustls
    "compression-gzip", # gzip compression
    "compression-zstd", # zstd compression
]}

Complete configuration example

Environment file (.env)

# Service identification
OTEL_SERVICE_NAME=my-rust-service
OTEL_RESOURCE_ATTRIBUTES=service.version=1.0.0,deployment.environment=production

# OTLP exporter
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_HEADERS=api-key=secret123
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_TIMEOUT=30000

# Batch processing
OTEL_BSP_MAX_QUEUE_SIZE=4096
OTEL_BSP_MAX_EXPORT_BATCH_SIZE=1024
OTEL_BSP_SCHEDULE_DELAY=10000

# Sampling
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

# Propagation
OTEL_PROPAGATORS=tracecontext,baggage

# Limits
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT=256
OTEL_SPAN_EVENT_COUNT_LIMIT=256

Cargo.toml

[dependencies]
opentelemetry = { version = "0.31", features = ["trace", "metrics", "logs"] }
opentelemetry_sdk = { version = "0.31", features = ["trace", "metrics", "logs", "rt-tokio"] }
opentelemetry-otlp = { version = "0.31", features = [
    "grpc-tonic",
    "compression-gzip",
    "reqwest-rustls",
]}

Application code

use opentelemetry::global;
use opentelemetry_sdk::{
    trace::{TracerProvider, BatchSpanProcessor},
    Resource,
    runtime::Tokio,
};
use opentelemetry_otlp::SpanExporter;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Resource detection uses OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES
    let resource = Resource::builder().build();
    
    // Exporter uses OTEL_EXPORTER_OTLP_* variables
    let exporter = SpanExporter::builder()
        .with_tonic()  // Uses OTEL_EXPORTER_OTLP_ENDPOINT
        .build()?;
    
    // Batch processor uses OTEL_BSP_* variables
    let processor = BatchSpanProcessor::builder(exporter, Tokio).build();
    
    let provider = TracerProvider::builder()
        .with_resource(resource)
        .with_span_processor(processor)
        .build();
    
    global::set_tracer_provider(provider);
    
    // Application code...
    
    global::shutdown_tracer_provider();
    Ok(())
}

Override precedence

Configuration is resolved in this order (highest to lowest priority):

Programmatic configuration - Values set in code
Environment variables - Runtime configuration
Default values - Built-in defaults

// Programmatic configuration takes precedence
let exporter = SpanExporter::builder()
    .with_tonic()
    .with_endpoint("http://custom-endpoint:4317")  // Overrides OTEL_EXPORTER_OTLP_ENDPOINT
    .build()?;

Best practices

Use environment variables for deployment - Different environments (dev, staging, prod) can have different configurations without code changes.

Validate configuration - Check that environment variables are set correctly before running in production.

Secure sensitive values - Don’t commit API keys or tokens to version control. Use secret management systems.

Feature flags reduce binary size - Only enable the features you need to minimize dependencies and compile time.

Configuration by environment

Development

OTEL_SERVICE_NAME=my-service-dev
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_TRACES_SAMPLER=always_on
OTEL_BSP_SCHEDULE_DELAY=1000  # Fast export for debugging

Staging

OTEL_SERVICE_NAME=my-service-staging
OTEL_EXPORTER_OTLP_ENDPOINT=https://staging-collector.example.com:4317
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.5  # 50% sampling
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging

Production

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com:4317
OTEL_EXPORTER_OTLP_HEADERS=api-key=${SECRET_API_KEY}
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1  # 10% sampling
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.version=${APP_VERSION}
OTEL_BSP_MAX_QUEUE_SIZE=8192  # Higher throughput

Resource detection

Configure resource attributes

Batch processing

Tune batch processor settings

Get Started

Core Concepts

Traces

Metrics

Logs

Exporters

Advanced

Examples

Overview

Environment variables

General configuration

OTLP exporter configuration

Signal-specific endpoints

Batch processor configuration

Trace configuration

Sampler types

Propagator configuration

Feature flags

opentelemetry crate

opentelemetry-sdk crate

opentelemetry-otlp crate

Complete configuration example

Environment file (.env)

Cargo.toml

Application code

Override precedence

Best practices

Configuration by environment

Development

Staging

Production

Resource detection

Batch processing

Build docs developers (and LLMs) love

Get Started

Core Concepts

Traces

Metrics

Logs

Exporters

Advanced

Examples

​Overview

​Environment variables

​General configuration

​OTLP exporter configuration

​Signal-specific endpoints

​Batch processor configuration

​Trace configuration

​Sampler types

​Propagator configuration

​Feature flags

​opentelemetry crate

​opentelemetry-sdk crate

​opentelemetry-otlp crate

​Complete configuration example

​Environment file (.env)

​Cargo.toml

​Application code

​Override precedence

​Best practices

​Configuration by environment

​Development

​Staging

​Production

​Related

Resource detection

Batch processing

Build docs developers (and LLMs) love

Overview

Environment variables

General configuration

OTLP exporter configuration

Signal-specific endpoints

Batch processor configuration

Trace configuration

Sampler types

Propagator configuration

Feature flags

opentelemetry crate

opentelemetry-sdk crate

opentelemetry-otlp crate

Complete configuration example

Environment file (.env)

Cargo.toml

Application code

Override precedence

Best practices

Configuration by environment

Development

Staging

Production

Related