tracing-opentelemetry-extra

Reference: This crate is mainly organized based on the official tracing-opentelemetry OTLP example.

This crate provides enhanced OpenTelemetry integration for tracing applications. It's based on the tracing-opentelemetry examples and provides a clean, easy-to-use API for setting up OpenTelemetry tracing and metrics.

Features

• Easy OpenTelemetry initialization with OTLP exporter
• Configurable sampling and resource attributes
• Automatic cleanup with guard pattern
• Support for tracing, metrics, and logs
• Clean separation of concerns from other tracing libraries

OTLP Protocol Configuration

This crate respects the standard OpenTelemetry protocol environment variables:

# Default protocol for all signals
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Specify Protocol for Traces, Metrics, and Logs:
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc

Supported values: grpc, http/protobuf (or http/proto), http/json.

Default behavior: when no protocol env vars are set, traces, metrics, and logs all use grpc.

Installation

Add this to your Cargo.toml:

[dependencies]
tracing-opentelemetry-extra = "0.31.x"

Quick Start

Basic Usage

use opentelemetry::KeyValue;
use tracing_opentelemetry_extra::{get_resource, init_tracer_provider, init_meter_provider, init_logger_provider, OtelGuard};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create resource with service name and attributes
    let resource = get_resource(
        "my-service",
        &[
            KeyValue::new("environment", "production"),
            KeyValue::new("version", "1.0.0"),
        ],
    );

    // Initialize providers
    let tracer_provider = init_tracer_provider(&resource, 1.0)?;
    let meter_provider = init_meter_provider(&resource, 30)?;
    let logger_provider = init_logger_provider(&resource)?;

    // Create guard for automatic cleanup
    let _guard = OtelGuard::new(Some(tracer_provider), Some(meter_provider), Some(logger_provider));

    // Your application code here...
    tracing::info!("Application started");

    // Cleanup is handled automatically when the guard is dropped
    Ok(())
}

With Tracing Subscriber

use opentelemetry::KeyValue;
use tracing::Level;
use tracing_opentelemetry_extra::{get_resource, init_tracer_provider, init_meter_provider, init_logger_provider, init_tracing_subscriber, init_env_filter, OtelGuard};
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create resource
    let service_name = "my-service";
    let resource = get_resource(service_name, &[KeyValue::new("environment", "production")]);
    
    // Initialize providers
    let tracer_provider = init_tracer_provider(&resource, 1.0)?;
    let meter_provider = init_meter_provider(&resource, 30)?;
    let logger_provider = init_logger_provider(&resource)?;

    // Set up tracing subscriber
    let env_filter = init_env_filter(&Level::INFO);
    
    // Create guard for cleanup (logger_provider is optional, pass None to disable OTel logs)
    let _guard = init_tracing_subscriber(
        service_name,
        env_filter,
        vec![Box::new(tracing_subscriber::fmt::layer())],
        tracer_provider,
        meter_provider,
        Some(logger_provider),
    )?;

    // Your application code here...
    tracing::info!("Application started with OpenTelemetry");

    Ok(())
}

Configuration

Sampling

Control the ratio of traces to sample (0.0 to 1.0):

// Sample 50% of traces
let tracer_provider = init_tracer_provider(&resource, 0.5)?;

// Sample all traces
let tracer_provider = init_tracer_provider(&resource, 1.0)?;

Metrics Collection

Configure the interval for metrics collection:

// Collect metrics every 60 seconds
let meter_provider = init_meter_provider(&resource, 60)?;

Resource Attributes

Add custom attributes to your service:

let resource = get_resource(
    "my-service",
    &[
        KeyValue::new("environment", "production"),
        KeyValue::new("version", "1.0.0"),
        KeyValue::new("region", "us-west-2"),
    ],
);

Features

• subscriber (default): Enables tracing-subscriber integration

Examples

See the examples directory for more detailed usage examples.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Related Crates

• tracing-otel-extra - HTTP, context, fields, and span utilities
• axum-otel - Axum web framework integration