From 03661dca48c50c814be38e07a8fdd07dcd83b8a0 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 13 Apr 2023 15:32:54 -0500 Subject: [PATCH 1/3] Drop log API include_trace_context parameter --- specification/logs/bridge-api.md | 9 ++------- specification/logs/sdk.md | 14 ++++++-------- 2 files changed, 8 insertions(+), 15 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 2a51cedf69b..7317d5384f4 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -85,15 +85,11 @@ This API MUST accept the following parameters: associate with emitted telemetry. This API MUST be structured to accept a variable number of attributes, including none. -* `include_trace_context` (optional): Specifies whether the Trace Context should - automatically be passed on to the `LogRecord`s emitted by the `Logger`. - If `include_trace_context` is not specified, it SHOULD be `true` by default. - `Logger`s are identified by `name`, `version`, and `schema_url` fields. When more than one `Logger` of the same `name`, `version`, and `schema_url` is created, it is unspecified whether or under which conditions the same or different `Logger` instances are returned. It is a user error to create Loggers with different -`include_trace_context` or `attributes` but the same identity. +`attributes` but the same identity. The term *identical* applied to `Logger`s describes instances where all identifying fields are equal. The term *distinct* applied to `Logger`s describes @@ -200,8 +196,7 @@ popular logging library. ### Implicit Context Injection When Context is implicitly available (e.g. in Java) the Appender can rely on -automatic context propagation by [obtaining a Logger](#get-a-logger) -with `include_trace_context=true`. +automatic context propagation by [obtaining a Logger](#get-a-logger). Some log libraries have mechanisms specifically tailored for injecting contextual information into logs, such as MDC in Log4j. When available such mechanisms may diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 08300accdd3..515668404f4 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -120,10 +120,6 @@ registered [LogRecordProcessors](#logrecordprocessor). ## Logger -If a `Logger` was obtained with `include_trace_context=true`, the `LogRecord`s -it [emits](./bridge-api.md#emit-a-logrecord) MUST automatically include the Trace -Context from the active Context, if Context has not been explicitly set. - Note that `Logger`s should not be responsible for configuration. This should be the responsibility of the `LoggerProvider` instead. @@ -140,6 +136,10 @@ access the [Instrumentation Scope](./data-model.md#field-instrumentationscope) and [Resource](./data-model.md#field-resource) information (implicitly) associated with the `LogRecord`. +The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from +the resolved `Context` (either the explicitly passed `Context` or the +current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord). + Counts for attributes due to collection limits MUST be available for exporters to report as described in the [transformation to non-OTLP formats](../common/mapping-to-non-otlp.md#dropped-attributes-count) @@ -234,10 +234,8 @@ therefore it SHOULD NOT block or throw exceptions. * `logRecord` - a [ReadWriteLogRecord](#readwritelogrecord) for the emitted `LogRecord`. -* `context` - the `Context` that the SDK determined (the explicitly - passed `Context`, the current `Context`, or an empty `Context` if - the [Logger](./bridge-api.md#get-a-logger) was obtained - with `include_trace_context=false`) +* `context` - the resolved `Context` (the explicitly passed `Context` or the + current `Context`) **Returns:** `Void` From 9d5c028fa71d5756bdf2154c95bf0a59340e00c6 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 13 Apr 2023 15:34:26 -0500 Subject: [PATCH 2/3] Changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b9e7bad2a4..a376de4753c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,8 @@ release. - Clarify parameters for emitting a log record. ([#3345](https://github.com/open-telemetry/opentelemetry-specification/pull/3354)) +- Drop logger include_trace_context parameter. + ([#3397](https://github.com/open-telemetry/opentelemetry-specification/pull/3397)) ### Resource From 3bb169f88cb720aef93aa253bfe2070c926888ea Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Fri, 14 Apr 2023 10:09:12 -0500 Subject: [PATCH 3/3] Rephrase implicit / explicit context injection sections --- specification/logs/bridge-api.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 7317d5384f4..147a1c6a883 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -196,29 +196,33 @@ popular logging library. ### Implicit Context Injection When Context is implicitly available (e.g. in Java) the Appender can rely on -automatic context propagation by [obtaining a Logger](#get-a-logger). +automatic context propagation by NOT explicitly setting `Context` when +calling [emit a LogRecord](#emit-a-logrecord). -Some log libraries have mechanisms specifically tailored for injecting contextual -information into logs, such as MDC in Log4j. When available such mechanisms may -be the preferable place to fetch the `TraceContext` and inject it into -the `LogRecord`, since it usually allows fetching of the context to work -correctly even when log records are emitted asynchronously, which otherwise can -result in the incorrect implicit context being fetched. +Some log libraries have mechanisms specifically tailored for injecting +contextual information info logs, such as MDC in Log4j. When available, it may +be preferable to use these mechanisms to set the Context. A log appender can +then fetch the Context and explicitly set it when +calling [emit a LogRecord](#emit-a-logrecord). This allows the correct Context +to be included even when log records are emitted asynchronously, which can +otherwise lead the Context to be incorrect. TODO: clarify how works or doesn't work when the log statement call site and the log appender are executed on different threads. ### Explicit Context Injection -In languages where the Context must be provided explicitly (e.g. Go) the end -user must capture the context and explicitly pass it to the logging subsystem in -order for `TraceContext` to be recorded in `LogRecord`s. +In order for `TraceContext` to be recorded in `LogRecord`s in languages where +the Context must be provided explicitly (e.g. Go), the end user must capture the +Context and explicitly pass it to the logging subsystem. The log appender must +take this Context and explicitly set it when +calling [emit a LogRecord](#emit-a-logrecord). Support for OpenTelemetry for logging libraries in these languages typically can be implemented in the form of logger wrappers that can capture the context once, when the span is created and then use the wrapped logger to execute log statements in a normal way. The wrapper will be responsible for injecting the -captured context in the `LogRecord`s. +captured context in the logs. This specification does not define how exactly it is achieved since the actual mechanism depends on the language and the particular logging library used. In