more wordings.

Author: cijothomas

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.
+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

@@ -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