Skip to content

Commit 1dd206b

Browse files
committed
chore(docs): clarify trace correlation via direct OpenTelemetry context and MDC
1 parent 1181b3b commit 1dd206b

1 file changed

Lines changed: 16 additions & 12 deletions

File tree

OBSERVABILITY.md

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -94,18 +94,22 @@ GAX and Google Cloud Java libraries use SLF4J for logging. Include an SLF4J impl
9494

9595
### 3.2 Correlating Logs with Cloud Trace
9696

97-
To correlate logs with Cloud Trace, ensure that active trace and span IDs are propagated to your logging framework's Mapped Diagnostic Context (MDC):
98-
1. Use the [OpenTelemetry Javaagent](https://opentelemetry.io/docs/zero-code/java/agent/), which automatically instruments logging frameworks.
99-
2. Or add the Logback MDC dependency to your project:
100-
```xml
101-
<dependency>
102-
<groupId>io.opentelemetry.instrumentation</groupId>
103-
<artifactId>opentelemetry-logback-mdc-1.0</artifactId>
104-
<version>2.10.0-alpha</version>
105-
</dependency>
106-
```
107-
108-
Once the MDC is populated with `trace_id` and `span_id`, the Google Cloud Logging Logback appender automatically maps these to the trace and span fields in Cloud Logging, allowing you to view correlated logs and traces in the Google Cloud Console.
97+
Google Cloud Java client libraries provide two complementary ways to correlate logs with Cloud Trace:
98+
99+
1. **Automatic Context Extraction in Cloud Logging**:
100+
When writing logs via `google-cloud-logging` (including via the Google Cloud Logging Logback appender), the client library automatically inspects the active thread's OpenTelemetry context (`Span.current()`). If a valid span is active, the `trace`, `spanId`, and `traceSampled` fields are automatically populated on the written `LogEntry`, linking the log directly to Cloud Trace in the Google Cloud Console.
101+
102+
2. **SLF4J Mapped Diagnostic Context (MDC) Propagation**:
103+
To also include `trace_id` and `span_id` in formatted log messages (such as console or file pattern layouts via `%X{trace_id}`) and attach them as labels in Logback, propagate the OpenTelemetry context to SLF4J MDC:
104+
- **OpenTelemetry Javaagent**: Use the [OpenTelemetry Javaagent](https://opentelemetry.io/docs/zero-code/java/agent/), which automatically instruments logging frameworks.
105+
- **Logback MDC Dependency**: Or add the Logback MDC instrumentation dependency to your project:
106+
```xml
107+
<dependency>
108+
<groupId>io.opentelemetry.instrumentation</groupId>
109+
<artifactId>opentelemetry-logback-mdc-1.0</artifactId>
110+
<version>2.10.0-alpha</version>
111+
</dependency>
112+
```
109113

110114
---
111115

0 commit comments

Comments
 (0)