From ce164d5976a5089bbd6c8fc09416442a3f5100df Mon Sep 17 00:00:00 2001
From: Cijo Thomas <cijo.thomas@gmail.com>
Date: Tue, 5 Aug 2025 09:26:12 -0700
Subject: [PATCH 01/10] 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 13c6e173e8fc9e517c6caa6a7ffefdaa55f564b7 Mon Sep 17 00:00:00 2001
From: Cijo Thomas <cijo.thomas@gmail.com>
Date: Tue, 5 Aug 2025 21:58:23 -0700
Subject: [PATCH 02/10] 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 b12ac8e26a3877117429acc070f10212ba04e5d4 Mon Sep 17 00:00:00 2001
From: Cijo Thomas <cijo.thomas@gmail.com>
Date: Tue, 5 Aug 2025 21:59:40 -0700
Subject: [PATCH 03/10] 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

From 369b73316e5c9161d6cd80af028f6a53db42d217 Mon Sep 17 00:00:00 2001
From: cijothomas <cijo.thomas@gmail.com>
Date: Mon, 11 May 2026 22:30:04 -0700
Subject: [PATCH 04/10] docs: refine logs and traces guidance

---
 docs/logs.md   |  70 +++++++++++++++++++++++--------
 docs/traces.md | 110 +++++++++++++++++++++++++------------------------
 2 files changed, 109 insertions(+), 71 deletions(-)

diff --git a/docs/logs.md b/docs/logs.md
index c6591960c1..340d42ec1b 100644
--- a/docs/logs.md
+++ b/docs/logs.md
@@ -1,18 +1,29 @@
 # OpenTelemetry Rust Logs
 
-Status: **Work-In-Progress**
+Status: **Stable**
 
 ## Introduction
 
-This document provides guidance on leveraging OpenTelemetry logs
-in Rust applications.
+This document provides guidance on leveraging OpenTelemetry logs in Rust
+applications.
 
-## OTel Log Bridge API
+In short: use [`tracing`] for logs and events; OpenTelemetry plugs in via the
+[`opentelemetry-appender-tracing`] appender. For span guidance, see
+[traces.md](traces.md).
 
-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.
+[`tracing`]: https://crates.io/crates/tracing
+[`opentelemetry-appender-tracing`]: ../opentelemetry-appender-tracing/README.md
+
+## OpenTelemetry Log Bridge API
+
+The OpenTelemetry Log Bridge API (part of the `opentelemetry` crate) is public
+and technically usable directly, but OpenTelemetry Rust deliberately does not
+advertise it as an end-user logging API. Instead, we point users at `tracing`
+and its existing ecosystem, with the Log Bridge API reserved for authoring
+appenders. Bridges for the
+[`tracing`](https://docs.rs/opentelemetry-appender-tracing/) and
+[`log`](https://docs.rs/opentelemetry-appender-log/) crates are already
+available.
 
 ## Instrumentation Guidance
 
@@ -20,12 +31,33 @@ appenders that bridge existing logging systems with OpenTelemetry. Bridges for
    [`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.
+2. **Lean on the `tracing` ecosystem**: OpenTelemetry doesn't replace what
+   `tracing` already offers. The appender is a standard `tracing-subscriber`
+   `Layer`, so it composes with `fmt::Layer`, `EnvFilter`, and any other
+   existing layer — for example, sending logs to stdout via `tracing`'s
+   `fmt::Layer` while also exporting via OpenTelemetry, or filtering what
+   reaches the OpenTelemetry pipeline. Use `tracing`'s ecosystem directly;
+   OpenTelemetry just plugs into it. (OpenTelemetry Rust does not currently
+   offer a production-ready stdout log exporter.)
+
+3. **Explicitly provide `name` and `target` fields**: These map to OpenTelemetry's
+   EventName and Instrumentation Scope respectively. Without them, `tracing`
+   synthesizes a `name` from the source location (e.g. `event src/foo.rs:42`)
+   and uses the module path as `target`, neither of which is meaningful as an
+   EventName or Instrumentation Scope.
+
+4. **Trace correlation is automatic**: When a log is emitted inside an active
+   OpenTelemetry span, the appender attaches the current `TraceId` and `SpanId`
+   to the resulting `LogRecord`. No extra wiring is required.
+
+5. **In-proc contextual enrichment via `tracing::span!`**: Use `tracing::span!`
+   to attach contextual attributes (e.g. `session.id`, `request.id`) that
+   should apply to every log inside that scope. The appender supports copying
+   these span attributes onto each emitted `LogRecord` via the experimental
+   `experimental_span_attributes` cargo feature; see the
+   [appender README](../opentelemetry-appender-tracing/README.md) for usage.
 
-3. **For setup details**: See
-   [`opentelemetry-appender-tracing`](https://docs.rs/opentelemetry-appender-tracing/)
-   for mapping details and code examples.
+### Example
 
 ```rust
 use tracing::error;
@@ -40,14 +72,18 @@ error!(
 
 ## 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.
+OpenTelemetry defines Events as Logs with an EventName. When you follow the guidance
+above and explicitly set the `name` field on every `tracing` log, each log maps to
+an OpenTelemetry Event. (Without an explicit `name`, the synthesized source-location
+string is technically present but is not a meaningful EventName.)
 
-**Note**: These are **not** mapped to Span Events. If you want to emit Span Events,
-use [`tracing-opentelemetry`](https://docs.rs/tracing-opentelemetry/).
+**Note**: These are **not** mapped to Span Events. OpenTelemetry is deprecating
+Span Events in favor of Events (Logs with an EventName), so use Events as
+described above rather than Span Events.
 
 ## See Also
 
+- [Main README](../README.md) — setup guidance for logging libraries and appenders
 - [OpenTelemetry Logs
   Specification](https://opentelemetry.io/docs/specs/otel/logs/)
 - [`tracing` Documentation](https://docs.rs/tracing/)
diff --git a/docs/traces.md b/docs/traces.md
index 57ee15fa33..503c329674 100644
--- a/docs/traces.md
+++ b/docs/traces.md
@@ -4,60 +4,62 @@ Status: **Work-In-Progress**
 
 ## Introduction
 
-This document provides comprehensive guidance on leveraging OpenTelemetry traces
-in Rust applications.
+This document provides 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.
+In short: use the OpenTelemetry Tracing API to create spans; [`tracing`] is
+for logs and events, not spans. See [logs.md](logs.md) for log guidance.
 
-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**
+## Instrumentation Guidance
 
-   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.
+1. **Use the OpenTelemetry Tracing API to create spans.** The
+   `opentelemetry::trace` API is designed around the OpenTelemetry
+   specification, with first-class support for span kind
+   (server/client/producer/consumer/internal), links, remote parents, and
+   context propagation across process boundaries.
+
+2. **[`tracing`] is not a complete substitute for the OpenTelemetry Tracing API.**
+   The `tracing` crate does not have a first-class notion of an OpenTelemetry
+   Span. It cannot, on its own, set span kind, attach links, or set a remote
+   parent — concepts central to the OpenTelemetry specification, particularly
+   for *edge* spans (see #3 below for nuance). Use it primarily for
+   logs/events (see [logs.md](logs.md)).
+
+3. **Bridging from `tracing::span!` to OpenTelemetry spans.** If you are
+   already using `tracing::span!` and want those spans surfaced as
+   OpenTelemetry spans, the third-party [`tracing-opentelemetry`] crate
+   provides a bridge. It is maintained outside the OpenTelemetry project and
+   is not part of this repo; we point to it so users are aware of the option
+   in the broader ecosystem.
+
+   For *internal* spans (spans that represent in-process work and never cross
+   a process boundary), `tracing::span!` through this bridge produces a
+   result nearly identical to using the OpenTelemetry Tracing API directly —
+   span kind, links, and remote parent are not relevant for internal spans.
+   The `tracing` limitations matter primarily for *edge* spans (e.g.,
+   incoming/outgoing HTTP, messaging), where span kind, links, and remote
+   parents are central to the OpenTelemetry data model. The bridge offers
+   extension APIs to express these concepts.
+
+4. **Prefer instrumentation libraries.** For framework-level spans (HTTP
+   servers/clients, database drivers, messaging), prefer instrumentation
+   libraries that use the OpenTelemetry Tracing API directly. No stable
+   instrumentation libraries exist yet in the OpenTelemetry Rust ecosystem,
+   but in-progress ones for Tower and Actix-Web exist in the
+   [opentelemetry-rust-contrib] repository:
+   [`opentelemetry-instrumentation-tower`] and
+   [`opentelemetry-instrumentation-actix-web`].
+
+## See Also
+
+- [OpenTelemetry Traces Specification](https://opentelemetry.io/docs/specs/otel/trace/)
+- [Main README](../README.md)
+- [logs.md](logs.md) — guidance for logs/events
+- [examples/tracing-http-propagator](../examples/tracing-http-propagator/) — end-to-end span creation and W3C context propagation
+- [examples/tracing-grpc](../examples/tracing-grpc/) — span creation and propagation over gRPC
+
+[`tracing`]: https://crates.io/crates/tracing
+[`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
+[opentelemetry-rust-contrib]: https://github.com/open-telemetry/opentelemetry-rust-contrib
+[`opentelemetry-instrumentation-tower`]: https://github.com/open-telemetry/opentelemetry-rust-contrib/tree/main/opentelemetry-instrumentation-tower
+[`opentelemetry-instrumentation-actix-web`]: https://github.com/open-telemetry/opentelemetry-rust-contrib/tree/main/opentelemetry-instrumentation-actix-web

From 0ee48712a32f1f6be59d1ead1467294522fa43fb Mon Sep 17 00:00:00 2001
From: cijothomas <cijo.thomas@gmail.com>
Date: Mon, 11 May 2026 22:34:40 -0700
Subject: [PATCH 05/10] docs(logs): note existing tracing/log instrumentation
 works as-is

---
 docs/logs.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/logs.md b/docs/logs.md
index 340d42ec1b..c7d6b8ee8e 100644
--- a/docs/logs.md
+++ b/docs/logs.md
@@ -8,7 +8,9 @@ This document provides guidance on leveraging OpenTelemetry logs in Rust
 applications.
 
 In short: use [`tracing`] for logs and events; OpenTelemetry plugs in via the
-[`opentelemetry-appender-tracing`] appender. For span guidance, see
+[`opentelemetry-appender-tracing`] appender. Existing `tracing` (or `log`)
+instrumentation continues to work as-is — adopting OpenTelemetry for logs is
+a setup change, not a code rewrite. For span guidance, see
 [traces.md](traces.md).
 
 [`tracing`]: https://crates.io/crates/tracing

From 58cc0b5c873a88f90acd6d0ede3d1ba550037399 Mon Sep 17 00:00:00 2001
From: cijothomas <cijo.thomas@gmail.com>
Date: Mon, 11 May 2026 22:36:39 -0700
Subject: [PATCH 06/10] docs(logs): reframe ecosystem example as stdout via fmt
 + OTLP via OTel

---
 docs/logs.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/logs.md b/docs/logs.md
index c7d6b8ee8e..d7fde579f9 100644
--- a/docs/logs.md
+++ b/docs/logs.md
@@ -37,10 +37,9 @@ available.
    `tracing` already offers. The appender is a standard `tracing-subscriber`
    `Layer`, so it composes with `fmt::Layer`, `EnvFilter`, and any other
    existing layer — for example, sending logs to stdout via `tracing`'s
-   `fmt::Layer` while also exporting via OpenTelemetry, or filtering what
-   reaches the OpenTelemetry pipeline. Use `tracing`'s ecosystem directly;
-   OpenTelemetry just plugs into it. (OpenTelemetry Rust does not currently
-   offer a production-ready stdout log exporter.)
+   `fmt::Layer` while exporting the same logs to an OTLP endpoint via
+   OpenTelemetry, or filtering what reaches the OpenTelemetry pipeline. Use
+   `tracing`'s ecosystem directly; OpenTelemetry just plugs into it.
 
 3. **Explicitly provide `name` and `target` fields**: These map to OpenTelemetry's
    EventName and Instrumentation Scope respectively. Without them, `tracing`

From 49accf4916da077f86bf753e7797c9bc7784630b Mon Sep 17 00:00:00 2001
From: cijothomas <cijo.thomas@gmail.com>
Date: Mon, 11 May 2026 22:39:39 -0700
Subject: [PATCH 07/10] docs(logs): use OTel semantic conventions in example

---
 docs/logs.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/logs.md b/docs/logs.md
index d7fde579f9..2cd799a2ca 100644
--- a/docs/logs.md
+++ b/docs/logs.md
@@ -63,9 +63,11 @@ available.
 ```rust
 use tracing::error;
 error!(
-    name: "database_connection_failed",
-    target: "database",
-    error_code = "CONNECTION_TIMEOUT",
+    name: "db.client.connection.failed",
+    target: "myapp.db",
+    db.system.name = "postgresql",
+    db.namespace = "orders",
+    error.type = "connection_timeout",
     retry_count = 3,
     message = "Failed to connect to database after retries"
 );

From f9c900b9ad245d69031d5c7603467dae89fdb0f7 Mon Sep 17 00:00:00 2001
From: cijothomas <cijo.thomas@gmail.com>
Date: Mon, 11 May 2026 22:43:22 -0700
Subject: [PATCH 08/10] docs: add docs/README.md with guidance index and
 historical context

---
 docs/README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 docs/README.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000..236c7b4c3c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,44 @@
+# OpenTelemetry Rust Guidance
+
+Guidance documents for using OpenTelemetry in Rust applications.
+
+- [logs.md](logs.md) — Logs and Events
+- [traces.md](traces.md) — Distributed Traces
+- [metrics.md](metrics.md) — Metrics
+
+## Why this guidance exists
+
+Rust had a mature observability ecosystem before OpenTelemetry Rust matured.
+The [`tracing`] crate was created by the Tokio project for structured logging
+and in-process context propagation in async Rust, with deep integration into
+the async runtime. It was never designed around the OpenTelemetry data model.
+
+OpenTelemetry came later with a different scope: a vendor-neutral standard
+for **distributed** tracing — spans that cross process boundaries — adopting
+[W3C Trace Context] for propagation, with first-class concepts like span
+kind, links, and remote parents. The OpenTelemetry Tracing API in this repo
+is built around that data model.
+
+The third-party [`tracing-opentelemetry`] crate bridges `tracing` spans into
+OpenTelemetry spans. It predates parts of OpenTelemetry's evolution, and
+because `tracing` itself has no first-class notion of OpenTelemetry-specific
+span concepts, the bridge cannot fully express the OpenTelemetry model on
+its own.
+
+These docs reflect that history: we recommend `tracing` for logs and events
+(where it excels), and the OpenTelemetry Tracing API for spans (where it is
+the spec-aligned choice). For users invested in `tracing::span!`, the
+bridge remains a viable option, with the caveats noted in
+[traces.md](traces.md).
+
+## A note on guidance
+
+This is guidance, not policy. Rust users have a strong, established
+ecosystem and the freedom to combine these libraries in ways that fit their
+applications. Where we make a firm recommendation, it reflects what we
+believe gives the best alignment with the OpenTelemetry specification and
+the broadest compatibility — but the choice remains yours.
+
+[`tracing`]: https://crates.io/crates/tracing
+[`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
+[W3C Trace Context]: https://www.w3.org/TR/trace-context/

From be2cd56538d706acaf567a08d3e960b32f0d042e Mon Sep 17 00:00:00 2001
From: cijothomas <cijo.thomas@gmail.com>
Date: Mon, 11 May 2026 22:44:51 -0700
Subject: [PATCH 09/10] docs: add TODO sections noting areas to expand toward
 metrics.md depth

---
 docs/logs.md   | 12 ++++++++++++
 docs/traces.md | 14 ++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/docs/logs.md b/docs/logs.md
index 2cd799a2ca..37fa144460 100644
--- a/docs/logs.md
+++ b/docs/logs.md
@@ -92,3 +92,15 @@ described above rather than Span Events.
 - [`tracing` Documentation](https://docs.rs/tracing/)
 - [`opentelemetry-appender-tracing`
   Documentation](https://docs.rs/opentelemetry-appender-tracing/)
+
+## TODO
+
+This document is intentionally high-level. Areas to expand over time, similar
+to the depth in [metrics.md](metrics.md):
+
+- Best practices, with links to runnable examples
+- `LoggerProvider` lifecycle and shutdown
+- Performance considerations (allocation, attribute cost)
+- Attribute modelling and semantic conventions
+- Common pitfalls (lost logs, missing correlation, mis-set `target`)
+- Batching, exporter configuration, and back-pressure
diff --git a/docs/traces.md b/docs/traces.md
index 503c329674..b0f9189d90 100644
--- a/docs/traces.md
+++ b/docs/traces.md
@@ -58,6 +58,20 @@ for logs and events, not spans. See [logs.md](logs.md) for log guidance.
 - [examples/tracing-http-propagator](../examples/tracing-http-propagator/) — end-to-end span creation and W3C context propagation
 - [examples/tracing-grpc](../examples/tracing-grpc/) — span creation and propagation over gRPC
 
+## TODO
+
+This document is intentionally high-level. Areas to expand over time, similar
+to the depth in [metrics.md](metrics.md):
+
+- Best practices, with links to runnable examples
+- `TracerProvider` lifecycle and shutdown
+- Sampling strategies and configuration
+- Context propagation: W3C Trace Context, Baggage, custom propagators
+- Span attribute modelling and semantic conventions
+- Performance considerations (allocation, attribute cost, span overhead)
+- Common pitfalls (broken context, missed parents, mis-set span kind)
+- Batching, exporter configuration, and back-pressure
+
 [`tracing`]: https://crates.io/crates/tracing
 [`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
 [opentelemetry-rust-contrib]: https://github.com/open-telemetry/opentelemetry-rust-contrib

From c5f702dda5bce9fd9bdeddf355388db1b6ebae22 Mon Sep 17 00:00:00 2001
From: cijothomas <cijo.thomas@gmail.com>
Date: Tue, 12 May 2026 07:28:43 -0700
Subject: [PATCH 10/10] docs: address review feedback from @scottgerring

---
 docs/logs.md   | 18 +++++++++++-------
 docs/traces.md | 49 +++++++++++++++++++++++++++----------------------
 2 files changed, 38 insertions(+), 29 deletions(-)

diff --git a/docs/logs.md b/docs/logs.md
index 37fa144460..3d80f6acd1 100644
--- a/docs/logs.md
+++ b/docs/logs.md
@@ -7,10 +7,10 @@ Status: **Stable**
 This document provides guidance on leveraging OpenTelemetry logs in Rust
 applications.
 
-In short: use [`tracing`] for logs and events; OpenTelemetry plugs in via the
-[`opentelemetry-appender-tracing`] appender. Existing `tracing` (or `log`)
-instrumentation continues to work as-is — adopting OpenTelemetry for logs is
-a setup change, not a code rewrite. For span guidance, see
+In short: for application logging, use [`tracing`] with the
+[`opentelemetry-appender-tracing`] appender. Existing `tracing` or `log`
+instrumentation can continue to work as-is; adopting OpenTelemetry for logs
+is primarily a setup change, not a code rewrite. For span guidance, see
 [traces.md](traces.md).
 
 [`tracing`]: https://crates.io/crates/tracing
@@ -80,9 +80,13 @@ above and explicitly set the `name` field on every `tracing` log, each log maps
 an OpenTelemetry Event. (Without an explicit `name`, the synthesized source-location
 string is technically present but is not a meaningful EventName.)
 
-**Note**: These are **not** mapped to Span Events. OpenTelemetry is deprecating
-Span Events in favor of Events (Logs with an EventName), so use Events as
-described above rather than Span Events.
+**Note**: These are **not** mapped to Span Events. If you specifically need
+Span Events today, record them with the OpenTelemetry tracing API
+(`Span::add_event` / `add_event_with_timestamp`). Otherwise, prefer Events
+(Logs with an EventName) as described above. The OpenTelemetry specification
+is deprecating the *Span Events API* (see [OTEP-4430]) in favor of Events.
+
+[OTEP-4430]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4430-span-event-api-deprecation-plan.md
 
 ## See Also
 
diff --git a/docs/traces.md b/docs/traces.md
index b0f9189d90..43ec92ac45 100644
--- a/docs/traces.md
+++ b/docs/traces.md
@@ -7,30 +7,44 @@ Status: **Work-In-Progress**
 This document provides guidance on leveraging OpenTelemetry traces in Rust
 applications.
 
-In short: use the OpenTelemetry Tracing API to create spans; [`tracing`] is
-for logs and events, not spans. See [logs.md](logs.md) for log guidance.
+In short: prefer instrumentation libraries that use the OpenTelemetry Tracing
+API for framework-level spans, and use the OpenTelemetry Tracing API
+directly to create your own custom spans. [`tracing`] is for logs and events,
+not spans. See [logs.md](logs.md) for log guidance.
 
 ## Instrumentation Guidance
 
-1. **Use the OpenTelemetry Tracing API to create spans.** The
+1. **Prefer instrumentation libraries.** For framework-level spans (HTTP
+   servers/clients, database drivers, messaging), prefer instrumentation
+   libraries that use the OpenTelemetry Tracing API directly. Most
+   applications start by plugging these in to capture the
+   request/response/downstream shape, then add custom spans for in-process
+   work as needed. No stable instrumentation libraries exist yet in the
+   OpenTelemetry Rust ecosystem, but in-progress ones for Tower and
+   Actix-Web exist in the [opentelemetry-rust-contrib] repository:
+   [`opentelemetry-instrumentation-tower`] and
+   [`opentelemetry-instrumentation-actix-web`].
+
+2. **Use the OpenTelemetry Tracing API to create custom spans.** The
    `opentelemetry::trace` API is designed around the OpenTelemetry
    specification, with first-class support for span kind
    (server/client/producer/consumer/internal), links, remote parents, and
    context propagation across process boundaries.
 
-2. **[`tracing`] is not a complete substitute for the OpenTelemetry Tracing API.**
-   The `tracing` crate does not have a first-class notion of an OpenTelemetry
-   Span. It cannot, on its own, set span kind, attach links, or set a remote
-   parent — concepts central to the OpenTelemetry specification, particularly
-   for *edge* spans (see #3 below for nuance). Use it primarily for
-   logs/events (see [logs.md](logs.md)).
+3. **[`tracing`] is designed to collect structured, event-based diagnostic
+   information, and is not a complete substitute for the OpenTelemetry
+   Tracing API, which focuses on distributed tracing.** The `tracing` crate
+   does not have a first-class notion of an OpenTelemetry Span. It cannot,
+   on its own, set span kind, attach links, or set a remote parent —
+   concepts central to the OpenTelemetry specification, particularly for
+   *edge* spans (see #4 below for nuance). Use it primarily for logs and
+   events (see [logs.md](logs.md)).
 
-3. **Bridging from `tracing::span!` to OpenTelemetry spans.** If you are
+4. **Bridging from `tracing::span!` to OpenTelemetry spans.** If you are
    already using `tracing::span!` and want those spans surfaced as
    OpenTelemetry spans, the third-party [`tracing-opentelemetry`] crate
-   provides a bridge. It is maintained outside the OpenTelemetry project and
-   is not part of this repo; we point to it so users are aware of the option
-   in the broader ecosystem.
+   provides a bridge. It is maintained outside the OpenTelemetry project
+   and is not part of this repo; we mention it here for completeness.
 
    For *internal* spans (spans that represent in-process work and never cross
    a process boundary), `tracing::span!` through this bridge produces a
@@ -41,15 +55,6 @@ for logs and events, not spans. See [logs.md](logs.md) for log guidance.
    parents are central to the OpenTelemetry data model. The bridge offers
    extension APIs to express these concepts.
 
-4. **Prefer instrumentation libraries.** For framework-level spans (HTTP
-   servers/clients, database drivers, messaging), prefer instrumentation
-   libraries that use the OpenTelemetry Tracing API directly. No stable
-   instrumentation libraries exist yet in the OpenTelemetry Rust ecosystem,
-   but in-progress ones for Tower and Actix-Web exist in the
-   [opentelemetry-rust-contrib] repository:
-   [`opentelemetry-instrumentation-tower`] and
-   [`opentelemetry-instrumentation-actix-web`].
-
 ## See Also
 
 - [OpenTelemetry Traces Specification](https://opentelemetry.io/docs/specs/otel/trace/)