Crate opentelemetry_otlp

Expand description

§OpenTelemetry OTLP Exporter

The OTLP Exporter enables exporting telemetry data (logs, metrics, and traces) in the OpenTelemetry Protocol (OTLP) format to compatible backends. These backends include:

OpenTelemetry Collector
Open-source observability tools (Prometheus, Jaeger, etc.)
Vendor-specific monitoring platforms

This crate supports sending OTLP data via:

gRPC
HTTP (binary protobuf or JSON)

§Quickstart with OpenTelemetry Collector

§HTTP Transport (Port 4318)

Run the OpenTelemetry Collector:

$ docker run -p 4318:4318 otel/opentelemetry-collector:latest

Configure your application to export traces via HTTP:

use opentelemetry::global;
use opentelemetry::trace::Tracer;
use opentelemetry_otlp::Protocol;
use opentelemetry_otlp::WithExportConfig;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    // Initialize OTLP exporter using HTTP binary protocol
    let otlp_exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_http()
        .with_protocol(Protocol::HttpBinary)
        .build()?;

    // Create a tracer provider with the exporter
    let _ = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_simple_exporter(otlp_exporter)
        .build();

    // Get a tracer and create spans
    let tracer = global::tracer("my_tracer");
    tracer.in_span("doing_work", |_cx| {
        // Your application logic here...
    });

    Ok(())
}

§gRPC Transport (Port 4317)

Run the OpenTelemetry Collector:

$ docker run -p 4317:4317 otel/opentelemetry-collector:latest

Configure your application to export traces via gRPC:

use opentelemetry::global;
use opentelemetry::trace::Tracer;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    // Initialize OTLP exporter using gRPC (Tonic)
    let otlp_exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .build()?;

    // Create a tracer provider with the exporter
    let _ = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_simple_exporter(otlp_exporter)
        .build();

    // Get a tracer and create spans
    let tracer = global::tracer("my_tracer");
    tracer.in_span("doing_work", |_cx| {
        // Your application logic here...
    });

    Ok(())
}

§Using with Jaeger

Jaeger natively supports the OTLP protocol, making it easy to send traces directly:

$ docker run -p 16686:16686 -p 4317:4317 -e COLLECTOR_OTLP_ENABLED=true jaegertracing/all-in-one:latest

After running your application configured with the OTLP exporter, view traces at: http://localhost:16686

§Using with Prometheus

Prometheus natively supports accepting metrics via the OTLP protocol (HTTP/protobuf). You can run Prometheus with the following command:

docker run -p 9090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml --web.enable-otlp-receiver

(An empty prometheus.yml file is sufficient for this example.)

Modify your application to export metrics via OTLP:

use opentelemetry::global;
use opentelemetry::metrics::Meter;
use opentelemetry::KeyValue;
use opentelemetry_otlp::Protocol;
use opentelemetry_otlp::WithExportConfig;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    // Initialize OTLP exporter using HTTP binary protocol
    let exporter = opentelemetry_otlp::MetricExporter::builder()
        .with_http()
        .with_protocol(Protocol::HttpBinary)
        .with_endpoint("http://localhost:9090/api/v1/otlp/v1/metrics")
        .build()?;

    // Create a meter provider with the OTLP Metric exporter
    let meter_provider = opentelemetry_sdk::metrics::SdkMeterProvider::builder()
        .with_periodic_exporter(exporter)
        .build();
    global::set_meter_provider(meter_provider.clone());

    // Get a meter
    let meter = global::meter("my_meter");

    // Create a metric
    let counter = meter.u64_counter("my_counter").build();
    counter.add(1, &[KeyValue::new("key", "value")]);

    // Shutdown the meter provider. This will trigger an export of all metrics.
    meter_provider.shutdown()?;

    Ok(())
}

After running your application configured with the OTLP exporter, view metrics at: http://localhost:9090

§Show Logs, Metrics too (TODO)

§Performance

For optimal performance, a batch exporting processor is recommended as the simple processor will export each span synchronously on dropping, and is only good for test/debug purposes.

[dependencies]
opentelemetry-otlp = { version = "*", features = ["grpc-tonic"] }

use opentelemetry::global;
use opentelemetry::trace::Tracer;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    // First, create a OTLP exporter builder. Configure it as you need.
    let otlp_exporter = opentelemetry_otlp::SpanExporter::builder().with_tonic().build()?;
    // Then pass it into provider builder
    let _ = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(otlp_exporter)
        .build();
    let tracer = global::tracer("my_tracer");
    tracer.in_span("doing_work", |cx| {
        // Traced app logic here...
    });

    Ok(())
}

§Feature Flags

The following feature flags can enable exporters for different telemetry signals:

trace: Includes the trace exporters.
metrics: Includes the metrics exporters.
logs: Includes the logs exporters.

The following feature flags generate additional code and types:

serialize: Enables serialization support for type defined in this crate via serde.

The following feature flags offer additional configurations on gRPC:

For users using tonic as grpc layer:

grpc-tonic: Use tonic as grpc layer.
gzip-tonic: Use gzip compression for tonic grpc layer.
zstd-tonic: Use zstd compression for tonic grpc layer.
tls-roots: Adds system trust roots to rustls-based gRPC clients using the rustls-native-certs crate
tls-webpki-roots: Embeds Mozilla’s trust roots to rustls-based gRPC clients using the webpki-roots crate

The following feature flags offer additional configurations on http:

http-proto: Use http as transport layer, protobuf as body format. This feature is enabled by default.
reqwest-blocking-client: Use reqwest blocking http client. This feature is enabled by default.
reqwest-client: Use reqwest http client.
reqwest-rustls: Use reqwest with TLS with system trust roots via rustls-native-certs crate.
reqwest-rustls-webpki-roots: Use reqwest with TLS with Mozilla’s trust roots via webpki-roots crate.

§Kitchen Sink Full Configuration

Example showing how to override all configuration options.

Generally there are two parts of configuration. One is the exporter, the other is the provider. Users can configure the exporter using SpanExporter::builder() for traces, and MetricExporter::builder() + opentelemetry_sdk::metrics::PeriodicReader::builder() for metrics. Once you have an exporter, you can add it to either a opentelemetry_sdk::trace::SdkTracerProvider::builder() for traces, or opentelemetry_sdk::metrics::SdkMeterProvider::builder() for metrics.

use opentelemetry::{global, KeyValue, trace::Tracer};
use opentelemetry_sdk::{trace::{self, RandomIdGenerator, Sampler}, Resource};
use opentelemetry_sdk::metrics::Temporality;
use opentelemetry_otlp::{Protocol, WithExportConfig, WithTonicConfig};
use std::time::Duration;
use tonic::metadata::*;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    let mut map = MetadataMap::with_capacity(3);

    map.insert("x-host", "example.com".parse().unwrap());
    map.insert("x-number", "123".parse().unwrap());
    map.insert_bin("trace-proto-bin", MetadataValue::from_bytes(b"[binary data]"));
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .with_endpoint("http://localhost:4317")
        .with_timeout(Duration::from_secs(3))
        .with_metadata(map)
        .build()?;

    let tracer_provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(exporter)
        .with_sampler(Sampler::AlwaysOn)
        .with_id_generator(RandomIdGenerator::default())
        .with_max_events_per_span(64)
        .with_max_attributes_per_span(16)
        .with_resource(Resource::builder_empty().with_attributes([KeyValue::new("service.name", "example")]).build())
        .build();
    global::set_tracer_provider(tracer_provider.clone());
    let tracer = global::tracer("tracer-name");

    let exporter = opentelemetry_otlp::MetricExporter::builder()
       .with_tonic()
       .with_endpoint("http://localhost:4318/v1/metrics")
       .with_protocol(Protocol::Grpc)
       .with_timeout(Duration::from_secs(3))
       .build()
       .unwrap();

   let provider = opentelemetry_sdk::metrics::SdkMeterProvider::builder()
        .with_periodic_exporter(exporter)
        .with_resource(Resource::builder_empty().with_attributes([KeyValue::new("service.name", "example")]).build())
        .build();

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

    Ok(())
}

Structs§

ExportConfig: Configuration for the OTLP exporter.
HttpExporterBuilderhttp-proto or http-json: Configuration for the OTLP HTTP exporter.
HttpExporterBuilderSethttp-proto or http-json: Type to hold the HttpExporterBuilder and indicate it has been set.
LogExporterlogs and (http-proto or http-json or grpc-tonic): OTLP exporter that sends log data
MetricExportermetrics and (http-proto or http-json or grpc-tonic): Export metrics in OTEL format.
NoExporterBuilderSet: Type to indicate the builder does not have a client set.
SpanExportertrace and (http-proto or http-json or grpc-tonic): OTLP exporter that sends tracing data
TonicConfiggrpc-tonic: Configuration for tonic
TonicExporterBuildergrpc-tonic: Configuration for the tonic OTLP GRPC exporter.
TonicExporterBuilderSetgrpc-tonic: Type to hold the TonicExporterBuilder and indicate it has been set.

Enums§

Compression: The compression algorithm to use when sending data.
ExporterBuildError: Errors that can occur while building an exporter.
Protocol: The communication protocol to use when exporting data.

Constants§

OTEL_EXPORTER_OTLP_COMPRESSION: Compression algorithm to use, defaults to none.
OTEL_EXPORTER_OTLP_ENDPOINT: Target to which the exporter is going to send signals, defaults to https://localhost:4317. Learn about the relationship between this constant and metrics/spans/logs at https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#endpoint-urls-for-otlphttp
OTEL_EXPORTER_OTLP_ENDPOINT_DEFAULT: Default target to which the exporter is going to send signals.
OTEL_EXPORTER_OTLP_HEADERS: Key-value pairs to be used as headers associated with gRPC or HTTP requests Example: k1=v1,k2=v2 Note: as of now, this is only supported for HTTP requests.
OTEL_EXPORTER_OTLP_LOGS_COMPRESSIONlogs and (http-proto or http-json or grpc-tonic): Compression algorithm to use, defaults to none.
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTlogs and (http-proto or http-json or grpc-tonic): Target to which the exporter is going to send logs
OTEL_EXPORTER_OTLP_LOGS_HEADERSlogs and (http-proto or http-json or grpc-tonic): Key-value pairs to be used as headers associated with gRPC or HTTP requests for sending logs. Example: k1=v1,k2=v2 Note: this is only supported for HTTP.
OTEL_EXPORTER_OTLP_LOGS_TIMEOUTlogs and (http-proto or http-json or grpc-tonic): Maximum time the OTLP exporter will wait for each batch logs export.
OTEL_EXPORTER_OTLP_METRICS_COMPRESSIONmetrics and (http-proto or http-json or grpc-tonic): Compression algorithm to use, defaults to none.
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTmetrics and (http-proto or http-json or grpc-tonic): Target to which the exporter is going to send metrics, defaults to https://localhost:4317/v1/metrics. Learn about the relationship between this constant and default/spans/logs at https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#endpoint-urls-for-otlphttp
OTEL_EXPORTER_OTLP_METRICS_HEADERSmetrics and (http-proto or http-json or grpc-tonic): Key-value pairs to be used as headers associated with gRPC or HTTP requests for sending metrics. Example: k1=v1,k2=v2 Note: this is only supported for HTTP.
OTEL_EXPORTER_OTLP_METRICS_TIMEOUTmetrics and (http-proto or http-json or grpc-tonic): Max waiting time for the backend to process each metrics batch, defaults to 10s.
OTEL_EXPORTER_OTLP_PROTOCOL: Protocol the exporter will use. Either http/protobuf or grpc.
OTEL_EXPORTER_OTLP_PROTOCOL_DEFAULT: Default protocol, using http-json.
OTEL_EXPORTER_OTLP_TIMEOUT: Max waiting time for the backend to process each signal batch, defaults to 10 seconds.
OTEL_EXPORTER_OTLP_TIMEOUT_DEFAULT: Default max waiting time for the backend to process each signal batch.
OTEL_EXPORTER_OTLP_TRACES_COMPRESSIONtrace and (http-proto or http-json or grpc-tonic): Compression algorithm to use, defaults to none.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTtrace and (http-proto or http-json or grpc-tonic): Target to which the exporter is going to send spans, defaults to https://localhost:4317/v1/traces. Learn about the relationship between this constant and default/metrics/logs at https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#endpoint-urls-for-otlphttp
OTEL_EXPORTER_OTLP_TRACES_HEADERStrace and (http-proto or http-json or grpc-tonic): Key-value pairs to be used as headers associated with gRPC or HTTP requests for sending spans. Example: k1=v1,k2=v2 Note: this is only supported for HTTP.
OTEL_EXPORTER_OTLP_TRACES_TIMEOUTtrace and (http-proto or http-json or grpc-tonic): Max waiting time for the backend to process each spans batch, defaults to 10s.

Traits§

HasExportConfig: Provide access to the ExportConfig field within the exporter builders.
HasHttpConfighttp-proto or http-json: Expose interface for modifying builder config.
HasTonicConfiggrpc-tonic: Expose interface for modifying TonicConfig fields within the exporter builders.
WithExportConfig: Expose methods to override ExportConfig.
WithHttpConfighttp-proto or http-json: This trait will be implemented for every struct that implemented HasHttpConfig trait.
WithTonicConfiggrpc-tonic: Expose methods to override TonicConfig.

Crate opentelemetry_otlpCopy item path