Crate opentelemetry_otlp

Source
Expand description

The OTLP Exporter supports exporting logs, metrics and traces 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 telemetry in OTLP via grpc and http (in binary format). Supports for other format and protocol will be added in the future. The details of what’s currently offering in this crate can be found in this doc.

§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:latest

Then create a new Exporter, and Provider with the recommended defaults to start exporting telemetry.

You will have to build a OTLP exporter first. Create the correct exporter based on the signal you are looking to export SpanExporter::builder(), MetricExporter::builder(), LogExporter::builder() respectively for traces, metrics, and logs.

Once you have the exporter, you can create your Provider by starting with TracerProvider::builder(), SdkMeterProvider::builder(), and LoggerProvider::builder() respectively for traces, metrics, and logs.

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::TracerProvider::builder()
        .with_simple_exporter(otlp_exporter)
        .build();
    let tracer = global::tracer("my_tracer");
    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_sdk = { version = "*", features = ["async-std"] }
opentelemetry-otlp = { version = "*", features = ["grpc-tonic"] }
let tracer = opentelemetry_sdk::trace::TracerProvider::builder()
       .with_batch_exporter(
           opentelemetry_otlp::SpanExporter::builder()
               .with_tonic()
               .build()?,
           opentelemetry_sdk::runtime::Tokio,
        )
       .build();

§Feature Flags

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

  • trace: Includes the trace exporters (enabled by default).
  • 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 create via serde.
  • populate-logs-event-name: Enables sending LogRecord::event_name as an attribute with the key name

The following feature flags offer additional configurations on gRPC:

For users uses tonic as grpc layer:

  • grpc-tonic: Use tonic as grpc layer. This is enabled by default.
  • 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-webkpi-roots: Embeds Mozilla’s trust roots to rustls-based gRPC clients using the webkpi-roots crate

The following feature flags offer additional configurations on http:

  • http-proto: Use http as transport layer, protobuf as body format.
  • reqwest-blocking-client: Use reqwest blocking http client.
  • reqwest-client: Use reqwest http client.
  • reqwest-rustls: Use reqwest with TLS with system trust roots via rustls-native-certs crate.
  • reqwest-rustls-webkpi-roots: Use reqwest with TLS with Mozilla’s trust roots via webkpi-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::TracerProvider::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::TracerProvider::builder()
        .with_batch_exporter(exporter, opentelemetry_sdk::runtime::Tokio)
        .with_config(
            trace::Config::default()
                .with_sampler(Sampler::AlwaysOn)
                .with_id_generator(RandomIdGenerator::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")])),
        ).build();
    global::set_tracer_provider(tracer_provider);
    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 reader = opentelemetry_sdk::metrics::PeriodicReader::builder(exporter, opentelemetry_sdk::runtime::Tokio)
       .with_interval(std::time::Duration::from_secs(3))
        .with_timeout(Duration::from_secs(10))
       .build();

   let provider = opentelemetry_sdk::metrics::SdkMeterProvider::builder()
       .with_reader(reader)
        .with_resource(Resource::new(vec![KeyValue::new("service.name", "example")]))
        .build();

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

    Ok(())
}

Structs§

Enums§

  • Compression
    The compression algorithm to use when sending data.
  • Error
    Wrap type for errors from this crate.
  • Protocol
    The communication protocol to use when exporting data.

Constants§

Traits§