1![Tracing — Structured, application-level diagnostics][splash] 2 3[splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg 4 5# Tracing OpenTelemetry 6 7Utilities for adding [OpenTelemetry] interoperability to [`tracing`]. 8 9[![Crates.io][crates-badge]][crates-url] 10[![Documentation][docs-badge]][docs-url] 11[![Documentation (master)][docs-master-badge]][docs-master-url] 12[![MIT licensed][mit-badge]][mit-url] 13[![Build Status][actions-badge]][actions-url] 14[![Discord chat][discord-badge]][discord-url] 15![maintenance status][maint-badge] 16 17[Documentation][docs-url] | [Chat][discord-url] 18 19[crates-badge]: https://img.shields.io/crates/v/tracing-opentelemetry.svg 20[crates-url]: https://crates.io/crates/tracing-opentelemetry/0.18.0 21[docs-badge]: https://docs.rs/tracing-opentelemetry/badge.svg 22[docs-url]: https://docs.rs/tracing-opentelemetry/0.18.0/tracing_opentelemetry 23[docs-master-badge]: https://img.shields.io/badge/docs-master-blue 24[docs-master-url]: https://tracing-rs.netlify.com/tracing_opentelemetry 25[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg 26[mit-url]: LICENSE 27[actions-badge]: https://github.com/tokio-rs/tracing/workflows/CI/badge.svg 28[actions-url]:https://github.com/tokio-rs/tracing/actions?query=workflow%3ACI 29[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white 30[discord-url]: https://discord.gg/EeF3cQw 31[maint-badge]: https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg 32 33## Overview 34 35[`tracing`] is a framework for instrumenting Rust programs to collect 36structured, event-based diagnostic information. This crate provides a 37subscriber that connects spans from multiple systems into a trace and 38emits them to [OpenTelemetry]-compatible distributed tracing systems 39for processing and visualization. 40 41The crate provides the following types: 42 43* [`OpenTelemetryLayer`] adds OpenTelemetry context to all `tracing` [span]s. 44* [`OpenTelemetrySpanExt`] allows OpenTelemetry parent trace information to be 45 injected and extracted from a `tracing` [span]. 46 47[`OpenTelemetryLayer`]: https://docs.rs/tracing-opentelemetry/latest/tracing_opentelemetry/struct.OpenTelemetryLayer.html 48[`OpenTelemetrySpanExt`]: https://docs.rs/tracing-opentelemetry/latest/tracing_opentelemetry/trait.OpenTelemetrySpanExt.html 49[span]: https://docs.rs/tracing/latest/tracing/span/index.html 50[`tracing`]: https://crates.io/crates/tracing 51[OpenTelemetry]: https://opentelemetry.io/ 52 53*Compiler support: [requires `rustc` 1.56+][msrv]* 54 55[msrv]: #supported-rust-versions 56 57## Examples 58 59### Basic Usage 60 61```rust 62use opentelemetry::sdk::export::trace::stdout; 63use tracing::{error, span}; 64use tracing_subscriber::layer::SubscriberExt; 65use tracing_subscriber::Registry; 66 67fn main() { 68 // Install a new OpenTelemetry trace pipeline 69 let tracer = stdout::new_pipeline().install_simple(); 70 71 // Create a tracing layer with the configured tracer 72 let telemetry = tracing_opentelemetry::layer().with_tracer(tracer); 73 74 // Use the tracing subscriber `Registry`, or any other subscriber 75 // that impls `LookupSpan` 76 let subscriber = Registry::default().with(telemetry); 77 78 // Trace executed code 79 tracing::subscriber::with_default(subscriber, || { 80 // Spans will be sent to the configured OpenTelemetry exporter 81 let root = span!(tracing::Level::TRACE, "app_start", work_units = 2); 82 let _enter = root.enter(); 83 84 error!("This event will be logged in the root span."); 85 }); 86} 87``` 88 89### Visualization example 90 91```console 92# Run a supported collector like jaeger in the background 93$ docker run -d -p6831:6831/udp -p6832:6832/udp -p16686:16686 jaegertracing/all-in-one:latest 94 95# Run example to produce spans (from parent examples directory) 96$ cargo run --example opentelemetry 97 98# View spans (see the image below) 99$ firefox http://localhost:16686/ 100``` 101 102 103 104## Feature Flags 105 106 - `metrics`: Enables the [`MetricsSubscriber`] type, a [subscriber] that 107 exports OpenTelemetry metrics from specifically-named events. This enables 108 the `metrics` feature flag on the `opentelemetry` crate. 109 110## Supported Rust Versions 111 112Tracing Opentelemetry is built against the latest stable release. The minimum 113supported version is 1.56. The current Tracing version is not guaranteed to 114build on Rust versions earlier than the minimum supported version. 115 116Tracing follows the same compiler support policies as the rest of the Tokio 117project. The current stable Rust compiler and the three most recent minor 118versions before it will always be supported. For example, if the current stable 119compiler version is 1.45, the minimum supported version will not be increased 120past 1.42, three minor versions prior. Increasing the minimum supported compiler 121version is not considered a semver breaking change as long as doing so complies 122with this policy. 123 124## License 125 126This project is licensed under the [MIT license](LICENSE). 127 128### Contribution 129 130Unless you explicitly state otherwise, any contribution intentionally submitted 131for inclusion in Tracing by you, shall be licensed as MIT, without any additional 132terms or conditions. 133
