From 0049a4fc428e1df9c19c8016ac8fd064bfd7c1dd Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Tue, 5 Aug 2025 09:26:12 -0700 Subject: [PATCH 1/3] docs: start doc for distributed tracing and logs guidance --- docs/logs.md | 18 ++++++++++++++++ docs/traces.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/logs.md create mode 100644 docs/traces.md diff --git a/docs/logs.md b/docs/logs.md new file mode 100644 index 0000000000..58f584d473 --- /dev/null +++ b/docs/logs.md @@ -0,0 +1,18 @@ +# OpenTelemetry Rust Logs + +Status: **Work-In-Progress** + +## Introduction + +This document provides comprehensive guidance on leveraging OpenTelemetry +logs in Rust applications. + +## Instrumentation Guidance + +// TODO +// Draft points to cover +1. OTel Log-Bridge API is not meant for end-users +2. End users must use existing logging API and bridge them. +3. Recommend `tracing` +4. Recommendation about Name, Target, Message +5. add more. \ No newline at end of file diff --git a/docs/traces.md b/docs/traces.md new file mode 100644 index 0000000000..6b7fcefdc9 --- /dev/null +++ b/docs/traces.md @@ -0,0 +1,56 @@ +# OpenTelemetry Rust Traces + +Status: **Work-In-Progress** + +## Introduction + +This document provides comprehensive guidance on leveraging OpenTelemetry traces +in Rust applications. + +## Instrumentation Guidance + +1. **Use OTel API for distributed traces** + + Use the `opentelemetry::trace` API to create spans. This supports context + propagation, span kinds (server/client), links, and remote parents. + +2. **Use tracing for logs/events** + + Use `tracing::info!`, `tracing::event!`, etc. for structured logging. This + will be converted to OTel LogRecords via opentelemetry-appender-tracing and + will be automatically correlated with the current active OTel trace context + as well. + +3. **In-proc contextual enrichment for logs/events** + + This is not something OTel has a spec-ed out solution for. This is very + specific to the logging library (tracing) and its bridge. + + Use `tracing::span!` macros to add contextual metadata (e.g., filename) that + applies to a group of logs. The `otel-appender-tracing` crate will be + enhanced to extract span attributes and attach them to logs automatically. + +4. **If using tracing::span! to create spans** + + This is not directly supported by OpenTelemetry. Use the + `tracing-opentelemetry` bridge to convert tracing spans into OTel spans. + + There are some limitations with this approach arising due to `tracing`s lack of support for + creating Spans following OpenTelemetry specification. Examples include + - Cannot set remote parent + - Cannot specify span kind (e.g., server/client) + - Cannot add span links + + The bridge offers extension APIs to support some of these, but they are not + standard and are maintained outside the OpenTelemetry and Tracing project and + within the bridge itself. + + TODO: Should we make a recommendation about + avoiding this extension APIs for instrumentation? + +5. **Use instrumentation libraries when possible** + + If you're manually creating `tracing::span!` and converting to OTel span for + "edge" spans, consider using official instrumentation libraries where + available. These handle proper span creation and context propagation using + the OpenTelemetry API directly. From 80db9e8675e56f761379b9cc4d17b816bf68814e Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Tue, 5 Aug 2025 21:58:23 -0700 Subject: [PATCH 2/3] more wordings. --- docs/logs.md | 55 +++++++++++++++++++++++++++++++++++++++++--------- docs/traces.md | 12 ++++++++--- 2 files changed, 55 insertions(+), 12 deletions(-) diff --git a/docs/logs.md b/docs/logs.md index 58f584d473..c6591960c1 100644 --- a/docs/logs.md +++ b/docs/logs.md @@ -4,15 +4,52 @@ Status: **Work-In-Progress** ## Introduction -This document provides comprehensive guidance on leveraging OpenTelemetry -logs in Rust applications. +This document provides guidance on leveraging OpenTelemetry logs +in Rust applications. + +## OTel Log Bridge API + +The OpenTelemetry Log Bridge API (part of the `opentelemetry` crate) is **not intended +for direct use by application developers**. It is provided for authoring log +appenders that bridge existing logging systems with OpenTelemetry. Bridges for +`tracing` and `log` crates are already available. ## Instrumentation Guidance -// TODO -// Draft points to cover -1. OTel Log-Bridge API is not meant for end-users -2. End users must use existing logging API and bridge them. -3. Recommend `tracing` -4. Recommendation about Name, Target, Message -5. add more. \ No newline at end of file +1. **Use the `tracing` crate**: We strongly recommend using the + [`tracing`](https://crates.io/crates/tracing) crate for structured logging in + Rust applications. + +2. **Explicitly provide `name` and `target` fields**: These map to OpenTelemetry's + EventName and Instrumentation Scope respectively, instead of relying on defaults. + +3. **For setup details**: See + [`opentelemetry-appender-tracing`](https://docs.rs/opentelemetry-appender-tracing/) + for mapping details and code examples. + +```rust +use tracing::error; +error!( + name: "database_connection_failed", + target: "database", + error_code = "CONNECTION_TIMEOUT", + retry_count = 3, + message = "Failed to connect to database after retries" +); +``` + +## Terminology + +OpenTelemetry defines Events as Logs with an EventName. Since every log from the `tracing` +crate has a `name` field that maps to EventName, every log becomes an OpenTelemetry Event. + +**Note**: These are **not** mapped to Span Events. If you want to emit Span Events, +use [`tracing-opentelemetry`](https://docs.rs/tracing-opentelemetry/). + +## See Also + +- [OpenTelemetry Logs + Specification](https://opentelemetry.io/docs/specs/otel/logs/) +- [`tracing` Documentation](https://docs.rs/tracing/) +- [`opentelemetry-appender-tracing` + Documentation](https://docs.rs/opentelemetry-appender-tracing/) diff --git a/docs/traces.md b/docs/traces.md index 6b7fcefdc9..6265555a9f 100644 --- a/docs/traces.md +++ b/docs/traces.md @@ -23,13 +23,14 @@ in Rust applications. 3. **In-proc contextual enrichment for logs/events** - This is not something OTel has a spec-ed out solution for. This is very - specific to the logging library (tracing) and its bridge. - Use `tracing::span!` macros to add contextual metadata (e.g., filename) that applies to a group of logs. The `otel-appender-tracing` crate will be enhanced to extract span attributes and attach them to logs automatically. + OpenTelemetry does not have a spec-ed out solution for in-process contextual + enrichment. This is very specific to the logging library (tracing) and its + bridge. + 4. **If using tracing::span! to create spans** This is not directly supported by OpenTelemetry. Use the @@ -48,6 +49,11 @@ in Rust applications. TODO: Should we make a recommendation about avoiding this extension APIs for instrumentation? + If you are creating spans to track in-proc work (what OTel calls "internal" spans), + `tracing:span` API is sufficient with `tracing-opentelemetry` bridge converting the + `tracing` Span to OTel Span, and properly activating/de-activating OTel's context, + to ensure correlation. + 5. **Use instrumentation libraries when possible** If you're manually creating `tracing::span!` and converting to OTel span for From 640aa630a440449b3a929e739d20d63fe80098bc Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Tue, 5 Aug 2025 21:59:40 -0700 Subject: [PATCH 3/3] phrase better --- docs/traces.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/traces.md b/docs/traces.md index 6265555a9f..57ee15fa33 100644 --- a/docs/traces.md +++ b/docs/traces.md @@ -37,10 +37,11 @@ in Rust applications. `tracing-opentelemetry` bridge to convert tracing spans into OTel spans. There are some limitations with this approach arising due to `tracing`s lack of support for - creating Spans following OpenTelemetry specification. Examples include - - Cannot set remote parent - - Cannot specify span kind (e.g., server/client) - - Cannot add span links + creating Spans following OpenTelemetry specification. For example, + `tracing` is unable to: + - Set remote parent + - Specify span kind (e.g., server/client/producer/consumer). + - Add span links The bridge offers extension APIs to support some of these, but they are not standard and are maintained outside the OpenTelemetry and Tracing project and