docs: start doc for distributed tracing and logs guidance

Author: cijothomas

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.

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.