OpenTelemetry Rust API

This crate contains the OpenTelemetry API for Rust.

Overview

OpenTelemetry is an Observability framework and toolkit designed to create and manage telemetry data such as traces, metrics, and logs. OpenTelemetry is vendor- and tool-agnostic, meaning that it can be used with a broad variety of Observability backends, including open source tools like Jaeger and Prometheus, as well as commercial offerings.

OpenTelemetry is not an observability backend like Jaeger, Prometheus, or other commercial vendors. OpenTelemetry is focused on the generation, collection, management, and export of telemetry. A major goal of OpenTelemetry is that you can easily instrument your applications or systems, no matter their language, infrastructure, or runtime environment. Crucially, the storage and visualization of telemetry is intentionally left to other tools.

Compiler support: requires rustc 1.65+

What does this crate contain?

This crate is basic foundation for integrating OpenTelemetry into libraries and applications, encompassing several aspects of OpenTelemetry, such as context management and propagation, baggage, logging, tracing, and metrics. It follows the OpenTelemetry specification. Here's a breakdown of its components:

• Context API: Provides a way to manage and propagate context, which is essential for keeping track of trace execution across asynchronous tasks.
• Propagators API: Defines how context can be shared across process boundaries, ensuring continuity across microservices or distributed systems.
• Baggage API: Allows for the attachment of metadata (baggage) to telemetry, which can be used for sharing application-specific information across service boundaries.
• Logs Bridge API: Allows to bridge existing logging mechanisms with OpenTelemetry logging. This is NOT meant for end users to call, instead it is meant to enable writing bridges/appenders for existing logging mechanisms such as log or tracing.
• Tracing API: Offers a set of primitives to produce distributed traces to understand the flow of a request across system boundaries.
• Metrics API: Offers a set of primitives to produce measurements of operational metrics like latency, throughput, or error rates.

This crate serves as a facade or no-op implementation, meaning it defines the traits for instrumentation but does not itself implement the processing or exporting of telemetry data. This separation of concerns allows library authors to depend on the API crate without tying themselves to a specific implementation.

Actual implementation and the heavy lifting of telemetry data collection, processing, and exporting are delegated to the opentelemetry-sdk crate and various exporter crates such as opentelemetry-otlp. This architecture ensures that the final application can light up the instrumentation by integrating an SDK implementation.

Library authors are recommended to depend on this crate only. This approach is also aligned with the design philosophy of existing telemetry solutions in the Rust ecosystem, like tracing or log, where these crates only offer a facade and the actual functionality is enabled through additional crates.

Related crates

Unless you are a library author, you will almost always need to use additional crates along with this. Given this crate has no-op implementation only, an OpenTelemetry SDK is always required. opentelemetry-sdk is the official SDK implemented by OpenTelemetry itself, though it is possible to use a different sdk.

Additionally one or more exporters are also required to export telemetry to a destination. OpenTelemetry provides the following exporters:

• opentelemetry-stdout: Prints telemetry to stdout, primarily used for learning/debugging purposes.
• opentelemetry-otlp: Exports telemetry (logs, metrics and traces) in the OTLP format to an endpoint accepting OTLP. This could be the OTel Collector, telemetry backends like Jaeger, Prometheus or vendor specific endpoints.
• opentelemetry-zipkin: Exports telemetry (traces only) to Zipkin following OpenTelemetry to Zipkin specification
• opentelemetry-prometheus: Exports telemetry (metrics only) to Prometheus following OpenTelemetry to Prometheus specification

OpenTelemetry Rust also has a contrib repo, where additional exporters could be found. Check OpenTelemetry Registry for additional exporters and other related components as well.

Getting started

See docs.

Supported Rust Versions

OpenTelemetry is built against the latest stable release. The minimum supported version is 1.65. 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.49, the minimum supported version will not be increased past 1.46, 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.