diff --git a/docs/logs.md b/docs/logs.md new file mode 100644 index 0000000000..c6591960c1 --- /dev/null +++ b/docs/logs.md @@ -0,0 +1,55 @@ +# OpenTelemetry Rust Logs + +Status: **Work-In-Progress** + +## Introduction + +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 + +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 new file mode 100644 index 0000000000..57ee15fa33 --- /dev/null +++ b/docs/traces.md @@ -0,0 +1,63 @@ +# 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** + + 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 + `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. 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 + within the bridge itself. + + 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 + "edge" spans, consider using official instrumentation libraries where + available. These handle proper span creation and context propagation using + the OpenTelemetry API directly.