docs: start doc for distributed tracing and logs guidance

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/)

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.