Topics

#jaeger #logging #metrics #opentelemetry #prometheus #tracing #zipkin

Language breakdown

Rust 99.4%

Shell 0.4%

Jinja 0.2%

RenderScript 0.0%

▸ Files click to expand

README

OpenTelemetry Rust

The Rust OpenTelemetry implementation.

Overview

OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior. You can export and analyze them using [Prometheus], [Jaeger], and other observability tools.

Supported Rust Versions

[Prometheus]: https://prometheus.io [Jaeger]: https://www.jaegertracing.io

Project Status

The table below summarizes the overall status of each component. Some components include unstable features, which are documented in their respective crate documentation.

| Signal/Component | Overall Status | | --------------------------- | ------------------ | | Context | Beta | | Baggage | RC | | Propagators | Beta | | Logs-API* | Stable | | Logs-SDK | Stable | | Logs-OTLP Exporter | RC | | Logs-Appender-Tracing | Stable | | Metrics-API | Stable | | Metrics-SDK | Stable | | Metrics-OTLP Exporter | RC | | Metrics-Prometheus Exporter | Beta | | Traces-API | Beta | | Traces-SDK | Beta | | Traces-OTLP Exporter | Beta |

*OpenTelemetry Rust is not introducing a new end user callable Logging API. Instead, it provides Logs Bridge API, that allows one to write log appenders that can bridge existing logging libraries to the OpenTelemetry log data model. The following log appenders are available:

If you already use the logging APIs from above, continue to use them, and use the appenders above to bridge the logs to OpenTelemetry. If you are using a library not listed here, feel free to contribute a new appender for the same.

If you are starting fresh, we recommend using tracing as your logging API. It supports structured logging and is actively maintained. OpenTelemetry itself uses tracing for its internal logging.

Project versioning information and stability guarantees can be found here.

Getting Started

If you are new to OpenTelemetry, start with the getting started examples for logs, metrics or traces. This example demonstrates how to use OpenTelemetry for logs, metrics, and traces, and display telemetry data on your console.

For those using OTLP, the recommended OpenTelemetry Exporter for production scenarios, refer to the OTLP Example - HTTP and the OTLP Example - gRPC.

Additional examples for various integration patterns can be found in the examples directory.

Overview of crates

The following crates are maintained in this repo:

[opentelemetry] This is the OpenTelemetry API crate, and is the crate

required to instrument libraries and applications. It contains Context API, Baggage API, Propagators API, Logging Bridge API, Metrics API, and Tracing API.

[opentelemetry-sdk] This is the OpenTelemetry SDK crate, and contains the

official OpenTelemetry SDK implementation. It contains Logging SDK, Metrics SDK, and Tracing SDK. It also contains propagator implementations.

[opentelemetry-otlp] - exporter to send 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-stdout] exporter for sending logs, metrics and traces to

stdout, for learning/debugging purposes.

[opentelemetry-http] This crate contains utility functions to help with

exporting telemetry, propagation, over [http].

[opentelemetry-appender-log] This crate provides logging appender to route

logs emitted using the log crate to opentelemetry.

[opentelemetry-appender-tracing] This crate provides logging appender to

route logs emitted using the tracing crate to opentelemetry.

[opentelemetry-prometheus] provides a pipeline and exporter for sending

metrics to [Prometheus].

[opentelemetry-semantic-conventions] provides standard names and semantic

otel conventions.

In addition, there are several other useful crates in the OTel Rust Contrib repo. A lot of crates maintained outside OpenTelemetry owned repos can be found in the OpenTelemetry Registry.

[opentelemetry]: https://crates.io/crates/opentelemetry [opentelemetry-sdk]: https://crates.io/crates/opentelemetry-sdk [opentelemetry-appender-log]: https://crates.io/crates/opentelemetry-appender-log [opentelemetry-appender-tracing]: https://crates.io/crates/opentelemetry-appender-tracing [opentelemetry-http]: https://crates.io/crates/opentelemetry-http [opentelemetry-otlp]: https://crates.io/crates/opentelemetry-otlp [opentelemetry-stdout]: https://crates.io/crates/opentelemetry-stdout [opentelemetry-prometheus]: https://crates.io/crates/opentelemetry-prometheus [Prometheus]: https://prometheus.io [opentelemetry-semantic-conventions]: https://crates.io/crates/opentelemetry-semantic-conventions [http]: https://crates.io/crates/http

Supported Rust Versions

OpenTelemetry is built against the latest stable release. The minimum supported version is 1.75. 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.

Contributing

See the contributing file.

The Rust special interest group (SIG) meets on alternating weeks between Tuesday at 9:00 AM PT and Wednesday at 8:00 AM PT. The meeting is subject to change depending on contributors' availability. Check the OpenTelemetry community calendar for specific dates and for Zoom meeting links. "OTel Rust SIG" is the name of meeting for this group.

Meeting notes are available as a public Google doc. If you have trouble accessing the doc, please get in touch on the #otel-rust channel on CNCF Slack. If you are new to the CNCF Slack community, you can create an account.

The meeting is open for all to join. We invite everyone to join our meeting, regardless of your experience level. Whether you're a seasoned OpenTelemetry developer, just starting your journey, or simply curious about the work we do, you're more than welcome to participate!