Crate opentelemetry_otlp

The OTLP Exporter supports exporting trace and metric data in the OTLP format to the OpenTelemetry collector or other compatible backend. The OpenTelemetry Collector offers a vendor-agnostic implementation on how to receive, process, and export telemetry data. In addition, it removes the need to run, operate, and maintain multiple agents/collectors in order to support open-source telemetry data formats (e.g. Jaeger, Prometheus, etc.) sending to multiple open-source or commercial back-ends.

Currently, this crate only support sending tracing data or metrics in OTLP via grpc. Support for sending data via HTTP will be added in the future.

Quickstart

First make sure you have a running version of the opentelemetry collector you want to send data to:

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

Then install a new pipeline with the recommended defaults to start exporting telemetry.

use opentelemetry::trace::Tracer;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    // use tonic as grpc layer here.
    // If you want to use grpcio. enable `grpc-sys` feature and use with_grpcio function here.
    let tracer = opentelemetry_otlp::new_pipeline().with_tonic().install_simple()?;

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

    Ok(())
}

Performance

For optimal performance, a batch exporter is recommended as the simple exporter will export each span synchronously on dropping. You can enable the [rt-tokio], [rt-tokio-current-thread] or [rt-async-std] features and specify a runtime on the pipeline builder to have a batch exporter configured for you automatically.

[dependencies]
opentelemetry = { version = "*", features = ["async-std"] }
opentelemetry-otlp = { version = "*", features = ["grpc-sys"] }

let tracer = opentelemetry_otlp::new_pipeline()
    .install_batch(opentelemetry::runtime::AsyncStd)?;

Kitchen Sink Full Configuration

Example showing how to override all configuration options. See the OtlpPipelineBuilder docs for details of each option.

There are two types of configurations. The first is common configurations that is used by both tonic and grpcio. The other is configuration that only works with tonic or grpcio.

The OtlpPipelineBuilder will first config the configurations that shared by both grpc layers. Then users can choose their grpc layer by with_tonic or with_grpcio functions. User can then config anything that only works with specific grpc layers.

use opentelemetry::{KeyValue, trace::Tracer};
use opentelemetry::sdk::{trace::{self, IdGenerator, Sampler}, Resource};
use opentelemetry_otlp::{Protocol};
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 tracer = opentelemetry_otlp::new_pipeline()
        .with_endpoint("http://localhost:4317")
        .with_protocol(Protocol::Grpc)
        .with_timeout(Duration::from_secs(3))
        .with_trace_config(
            trace::config()
                .with_sampler(Sampler::AlwaysOn)
                .with_id_generator(IdGenerator::default())
                .with_max_events_per_span(64)
                .with_max_attributes_per_span(16)
                .with_max_events_per_span(16)
                .with_resource(Resource::new(vec![KeyValue::new("service.name", "example")])),
        )
        .with_tonic()
        .with_metadata(map)
        .install_batch(opentelemetry::runtime::Tokio)?;

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

    Ok(())
}

Grpc libraries comparison

The table below provides a short comparison between grpcio and tonic, two of the most popular grpc libraries in Rust. Users can choose between them when working with otlp with grpc as transport layer.

Project	hyperium/tonic	tikv/grpc-rs
Feature name	–features=default	–features=grpc-sys
gRPC library	tonic	grpcio
Transport	hyperium/hyper (Rust)	grpc/grpc (C++ binding)
TLS support	yes	yes
TLS optional	yes	yes
TLS library	rustls	OpenSSL
Supported .proto generator	prost	prost, protobuf

Modules

proto

Structs

Credentials	Credential configuration for authenticated requests.
ExporterConfig	Configuration for the OTLP exporter.
GrpcioConfig	Configuration of grpcio
GrpcioPipelineBuilder	Build a trace exporter that uses grpcio as grpc layer and opentelemetry protocol.
HttpConfig	Configuration of the http transport
HttpPipelineBuilder	Build a trace exporter that uses HTTP transport and opentelemetry protocol.
MetricsExporter	Export metrics in OTEL format.
OtlpMetricPipelineBuilder	Pipeline to build OTLP metrics exporter
OtlpPipelineBuilder	Recommended configuration for an OTLP exporter pipeline.
TonicConfig	Configuration for tonic
TonicPipelineBuilder	Build a trace exporter that uses tonic as grpc layer and opentelemetry protocol.

Enums

Compression	The compression algorithm to use when sending data.
Error	Wrap type for errors from opentelemetry otel
Protocol	The communication protocol to use when exporting data.
TraceExporter	Exporter that sends data in OTLP format.

Functions

new_metrics_pipeline	Return a pipeline to build OTLP metrics exporter.
new_pipeline	Create a new pipeline builder with the recommended configuration.