Crate opentelemetry

The Rust OpenTelemetry implementation.

OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.

Compiler support: requires rustc 1.42+

Getting Started

use opentelemetry::{sdk::export::trace::stdout, trace::Tracer};

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    // Create a new instrumentation pipeline
    let (tracer, _uninstall) = stdout::new_pipeline().install();

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

    Ok(())
}

See the examples directory for different integration patterns.

Crate Feature Flags

The following core crate feature flags are available:

• trace: Includes the trace API and SDK (enabled by default).
• metrics: Includes the unstable metrics API and SDK.
• serialize: Adds serde serializers for common types.

Support for recording and exporting telemetry asynchronously can be added via the following flags:

• tokio: Spawn telemetry tasks using tokio's runtime.
• async-std: Spawn telemetry tasks using async-std's runtime.

The following flags enable propagating information in other crate ecosystems:

• http: Propagate information via http header maps.
• tonic: Propagate information via tonic's metadata.

Finally the following flags can be used by exporter authors:

• reqwest: Implementation of HttpClient for reqwest.
• surf: Implementation of HttpClient for surf`.

Related Crates

In addition to opentelemetry, the open-telemetry/opentelemetry-rust repository contains several additional crates designed to be used with the opentelemetry ecosystem. This includes a collection of trace SpanExporter and metrics pull and push controller implementations, as well as utility and adapter crates to assist in propagating state and instrumenting applications.

In particular, the following crates are likely to be of interest:

• opentelemetry-jaeger provides a pipeline and exporter for sending trace information to Jaeger.
• opentelemetry-otlp exporter for sending trace and metric data in the OTLP format to the OpenTelemetry collector.
• opentelemetry-prometheus provides a pipeline and exporter for sending metrics information to Prometheus.
• opentelemetry-zipkin provides a pipeline and exporter for sending trace information to Zipkin.
• opentelemetry-contrib provides additional exporters to vendors like Datadog.
• opentelemetry-semantic-conventions provides standard names and semantic otel conventions.

Additionally, there are also several third-party crates which are not maintained by the opentelemetry project. These include:

• tracing-opentelemetry provides integration for applications instrumented using the tracing API and ecosystem.
• actix-web-opentelemetry provides integration for the actix-web web server and ecosystem.
• opentelemetry-application-insights provides an unofficial Azure Application Insights exporter.
• opentelemetry-tide provides integration for the Tide web server and ecosystem.
• opentelemetry-stackdriver provides an exporter for Google's Cloud Trace (which used to be called StackDriver).

If you're the maintainer of an opentelemetry ecosystem crate not listed above, please let us know! We'd love to add your project to the list!

Supported Rust Versions

OpenTelemetry is built against the latest stable release. The minimum supported version is 1.42. The current OpenTelemetry version is not guaranteed to build on Rust versions earlier than the minimum supported version.

The current stable Rust compiler and the three most recent minor versions before it will always be supported. For example, if the current stable compiler version is 1.45, the minimum supported version will not be increased past 1.42, three minor versions prior. Increasing the minimum supported compiler version is not considered a semver breaking change as long as doing so complies with this policy.

Modules

baggage	Primitives for sending name-value data across system boundaries.
global	Utilities for working with global telemetry primitives
labels	metrics OpenTelemetry Labels
metrics	metrics OpenTelemetry Metrics API
propagation	OpenTelemetry Propagator interface
sdk	OpenTelemetry SDK
testing
trace	trace OpenTelemetry Tracing API.

Structs

Context	An execution-scoped collection of values.
ContextGuard	A guard that resets the current context to the prior context when dropped.
Key	Key used for metric LabelSets and trace Span attributes.
KeyValue	KeyValue pairs are used by LabelSets and Span attributes.
Unit	Units denote underlying data units tracked by Meters.

Enums

Array	Array of homogeneous values
Value	Value types for use in KeyValue pairs.