(Draft) OTel Tracing guidelines #3121
Description
Recommended Tracing Usage in OpenTelemetry Rust
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. These will be automatically correlated with the current active OTel span when using the appropriate OpenTelemetry log appender.
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.
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.
Limitations of tracing spans:
• 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.
5. Use instrumentation libraries when possible
If you’re manually creating tracing::span! and converting to OTel spans, consider using official instrumentation libraries (e.g., actix-web, tower). These handle proper span creation and context propagation using the OpenTelemetry API directly.