otel-init 0.33.2

OpenTelemetry provider and subscriber initialization with lifecycle management.
Documentation

otel-init

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.

otel-init is the successor to tracing-opentelemetry-extra. It is a separate crates.io package, so applications must update both the Cargo dependency name and Rust imports; Cargo cannot migrate the package automatically. See the changelog for the migration steps.

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:

# No OTLP endpoint configured, or configured as an empty string:
# providers are initialized locally, trace IDs are still created, and nothing is exported.
#
# Enable OTLP export for all signals:
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Or enable one signal only:
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces

# 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 endpoint env vars are set, or endpoint env vars are empty, traces, metrics, and logs are local-only and do not attempt to connect to localhost:4317. When an endpoint is configured but no protocol env vars are set, traces, metrics, and logs all use grpc.

Installation

Add this to your Cargo.toml:

[dependencies]
otel-init = "0.33"

Quick Start

Basic Usage

use opentelemetry::KeyValue;
use otel_init::{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 otel_init::{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

at your option.

Related Crates