Skip to content

Commit 369b733

Browse files
cijothomascijothomas
committed
docs: refine logs and traces guidance
1 parent b12ac8e commit 369b733

2 files changed

Lines changed: 109 additions & 71 deletions

File tree

‎docs/logs.md‎

Lines changed: 53 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,63 @@
11
# OpenTelemetry Rust Logs
22

3-
Status: **Work-In-Progress**
3+
Status: **Stable**
44

55
## Introduction
66

7-
This document provides guidance on leveraging OpenTelemetry logs
8-
in Rust applications.
7+
This document provides guidance on leveraging OpenTelemetry logs in Rust
8+
applications.
99

10-
## OTel Log Bridge API
10+
In short: use [`tracing`] for logs and events; OpenTelemetry plugs in via the
11+
[`opentelemetry-appender-tracing`] appender. For span guidance, see
12+
[traces.md](traces.md).
1113

12-
The OpenTelemetry Log Bridge API (part of the `opentelemetry` crate) is **not intended
13-
for direct use by application developers**. It is provided for authoring log
14-
appenders that bridge existing logging systems with OpenTelemetry. Bridges for
15-
`tracing` and `log` crates are already available.
14+
[`tracing`]: https://crates.io/crates/tracing
15+
[`opentelemetry-appender-tracing`]: ../opentelemetry-appender-tracing/README.md
16+
17+
## OpenTelemetry Log Bridge API
18+
19+
The OpenTelemetry Log Bridge API (part of the `opentelemetry` crate) is public
20+
and technically usable directly, but OpenTelemetry Rust deliberately does not
21+
advertise it as an end-user logging API. Instead, we point users at `tracing`
22+
and its existing ecosystem, with the Log Bridge API reserved for authoring
23+
appenders. Bridges for the
24+
[`tracing`](https://docs.rs/opentelemetry-appender-tracing/) and
25+
[`log`](https://docs.rs/opentelemetry-appender-log/) crates are already
26+
available.
1627

1728
## Instrumentation Guidance
1829

1930
1. **Use the `tracing` crate**: We strongly recommend using the
2031
[`tracing`](https://crates.io/crates/tracing) crate for structured logging in
2132
Rust applications.
2233

23-
2. **Explicitly provide `name` and `target` fields**: These map to OpenTelemetry's
24-
EventName and Instrumentation Scope respectively, instead of relying on defaults.
34+
2. **Lean on the `tracing` ecosystem**: OpenTelemetry doesn't replace what
35+
`tracing` already offers. The appender is a standard `tracing-subscriber`
36+
`Layer`, so it composes with `fmt::Layer`, `EnvFilter`, and any other
37+
existing layer — for example, sending logs to stdout via `tracing`'s
38+
`fmt::Layer` while also exporting via OpenTelemetry, or filtering what
39+
reaches the OpenTelemetry pipeline. Use `tracing`'s ecosystem directly;
40+
OpenTelemetry just plugs into it. (OpenTelemetry Rust does not currently
41+
offer a production-ready stdout log exporter.)
42+
43+
3. **Explicitly provide `name` and `target` fields**: These map to OpenTelemetry's
44+
EventName and Instrumentation Scope respectively. Without them, `tracing`
45+
synthesizes a `name` from the source location (e.g. `event src/foo.rs:42`)
46+
and uses the module path as `target`, neither of which is meaningful as an
47+
EventName or Instrumentation Scope.
48+
49+
4. **Trace correlation is automatic**: When a log is emitted inside an active
50+
OpenTelemetry span, the appender attaches the current `TraceId` and `SpanId`
51+
to the resulting `LogRecord`. No extra wiring is required.
52+
53+
5. **In-proc contextual enrichment via `tracing::span!`**: Use `tracing::span!`
54+
to attach contextual attributes (e.g. `session.id`, `request.id`) that
55+
should apply to every log inside that scope. The appender supports copying
56+
these span attributes onto each emitted `LogRecord` via the experimental
57+
`experimental_span_attributes` cargo feature; see the
58+
[appender README](../opentelemetry-appender-tracing/README.md) for usage.
2559

26-
3. **For setup details**: See
27-
[`opentelemetry-appender-tracing`](https://docs.rs/opentelemetry-appender-tracing/)
28-
for mapping details and code examples.
60+
### Example
2961

3062
```rust
3163
use tracing::error;
@@ -40,14 +72,18 @@ error!(
4072

4173
## Terminology
4274

43-
OpenTelemetry defines Events as Logs with an EventName. Since every log from the `tracing`
44-
crate has a `name` field that maps to EventName, every log becomes an OpenTelemetry Event.
75+
OpenTelemetry defines Events as Logs with an EventName. When you follow the guidance
76+
above and explicitly set the `name` field on every `tracing` log, each log maps to
77+
an OpenTelemetry Event. (Without an explicit `name`, the synthesized source-location
78+
string is technically present but is not a meaningful EventName.)
4579

46-
**Note**: These are **not** mapped to Span Events. If you want to emit Span Events,
47-
use [`tracing-opentelemetry`](https://docs.rs/tracing-opentelemetry/).
80+
**Note**: These are **not** mapped to Span Events. OpenTelemetry is deprecating
81+
Span Events in favor of Events (Logs with an EventName), so use Events as
82+
described above rather than Span Events.
4883

4984
## See Also
5085

86+
- [Main README](../README.md) — setup guidance for logging libraries and appenders
5187
- [OpenTelemetry Logs
5288
Specification](https://opentelemetry.io/docs/specs/otel/logs/)
5389
- [`tracing` Documentation](https://docs.rs/tracing/)

‎docs/traces.md‎

Lines changed: 56 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -4,60 +4,62 @@ Status: **Work-In-Progress**
44

55
## Introduction
66

7-
This document provides comprehensive guidance on leveraging OpenTelemetry traces
8-
in Rust applications.
7+
This document provides guidance on leveraging OpenTelemetry traces in Rust
8+
applications.
99

10-
## Instrumentation Guidance
11-
12-
1. **Use OTel API for distributed traces**
13-
14-
Use the `opentelemetry::trace` API to create spans. This supports context
15-
propagation, span kinds (server/client), links, and remote parents.
16-
17-
2. **Use tracing for logs/events**
18-
19-
Use `tracing::info!`, `tracing::event!`, etc. for structured logging. This
20-
will be converted to OTel LogRecords via opentelemetry-appender-tracing and
21-
will be automatically correlated with the current active OTel trace context
22-
as well.
23-
24-
3. **In-proc contextual enrichment for logs/events**
25-
26-
Use `tracing::span!` macros to add contextual metadata (e.g., filename) that
27-
applies to a group of logs. The `otel-appender-tracing` crate will be
28-
enhanced to extract span attributes and attach them to logs automatically.
29-
30-
OpenTelemetry does not have a spec-ed out solution for in-process contextual
31-
enrichment. This is very specific to the logging library (tracing) and its
32-
bridge.
10+
In short: use the OpenTelemetry Tracing API to create spans; [`tracing`] is
11+
for logs and events, not spans. See [logs.md](logs.md) for log guidance.
3312

34-
4. **If using tracing::span! to create spans**
35-
36-
This is not directly supported by OpenTelemetry. Use the
37-
`tracing-opentelemetry` bridge to convert tracing spans into OTel spans.
38-
39-
There are some limitations with this approach arising due to `tracing`s lack of support for
40-
creating Spans following OpenTelemetry specification. For example,
41-
`tracing` is unable to:
42-
- Set remote parent
43-
- Specify span kind (e.g., server/client/producer/consumer).
44-
- Add span links
45-
46-
The bridge offers extension APIs to support some of these, but they are not
47-
standard and are maintained outside the OpenTelemetry and Tracing project and
48-
within the bridge itself.
49-
50-
TODO: Should we make a recommendation about
51-
avoiding this extension APIs for instrumentation?
52-
53-
If you are creating spans to track in-proc work (what OTel calls "internal" spans),
54-
`tracing:span` API is sufficient with `tracing-opentelemetry` bridge converting the
55-
`tracing` Span to OTel Span, and properly activating/de-activating OTel's context,
56-
to ensure correlation.
57-
58-
5. **Use instrumentation libraries when possible**
13+
## Instrumentation Guidance
5914

60-
If you're manually creating `tracing::span!` and converting to OTel span for
61-
"edge" spans, consider using official instrumentation libraries where
62-
available. These handle proper span creation and context propagation using
63-
the OpenTelemetry API directly.
15+
1. **Use the OpenTelemetry Tracing API to create spans.** The
16+
`opentelemetry::trace` API is designed around the OpenTelemetry
17+
specification, with first-class support for span kind
18+
(server/client/producer/consumer/internal), links, remote parents, and
19+
context propagation across process boundaries.
20+
21+
2. **[`tracing`] is not a complete substitute for the OpenTelemetry Tracing API.**
22+
The `tracing` crate does not have a first-class notion of an OpenTelemetry
23+
Span. It cannot, on its own, set span kind, attach links, or set a remote
24+
parent — concepts central to the OpenTelemetry specification, particularly
25+
for *edge* spans (see #3 below for nuance). Use it primarily for
26+
logs/events (see [logs.md](logs.md)).
27+
28+
3. **Bridging from `tracing::span!` to OpenTelemetry spans.** If you are
29+
already using `tracing::span!` and want those spans surfaced as
30+
OpenTelemetry spans, the third-party [`tracing-opentelemetry`] crate
31+
provides a bridge. It is maintained outside the OpenTelemetry project and
32+
is not part of this repo; we point to it so users are aware of the option
33+
in the broader ecosystem.
34+
35+
For *internal* spans (spans that represent in-process work and never cross
36+
a process boundary), `tracing::span!` through this bridge produces a
37+
result nearly identical to using the OpenTelemetry Tracing API directly —
38+
span kind, links, and remote parent are not relevant for internal spans.
39+
The `tracing` limitations matter primarily for *edge* spans (e.g.,
40+
incoming/outgoing HTTP, messaging), where span kind, links, and remote
41+
parents are central to the OpenTelemetry data model. The bridge offers
42+
extension APIs to express these concepts.
43+
44+
4. **Prefer instrumentation libraries.** For framework-level spans (HTTP
45+
servers/clients, database drivers, messaging), prefer instrumentation
46+
libraries that use the OpenTelemetry Tracing API directly. No stable
47+
instrumentation libraries exist yet in the OpenTelemetry Rust ecosystem,
48+
but in-progress ones for Tower and Actix-Web exist in the
49+
[opentelemetry-rust-contrib] repository:
50+
[`opentelemetry-instrumentation-tower`] and
51+
[`opentelemetry-instrumentation-actix-web`].
52+
53+
## See Also
54+
55+
- [OpenTelemetry Traces Specification](https://opentelemetry.io/docs/specs/otel/trace/)
56+
- [Main README](../README.md)
57+
- [logs.md](logs.md) — guidance for logs/events
58+
- [examples/tracing-http-propagator](../examples/tracing-http-propagator/) — end-to-end span creation and W3C context propagation
59+
- [examples/tracing-grpc](../examples/tracing-grpc/) — span creation and propagation over gRPC
60+
61+
[`tracing`]: https://crates.io/crates/tracing
62+
[`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
63+
[opentelemetry-rust-contrib]: https://github.com/open-telemetry/opentelemetry-rust-contrib
64+
[`opentelemetry-instrumentation-tower`]: https://github.com/open-telemetry/opentelemetry-rust-contrib/tree/main/opentelemetry-instrumentation-tower
65+
[`opentelemetry-instrumentation-actix-web`]: https://github.com/open-telemetry/opentelemetry-rust-contrib/tree/main/opentelemetry-instrumentation-actix-web

0 commit comments

Comments
 (0)