Add Advanced Processing to Logs Supplementary Guidelines by pellared · Pull Request #4407 · open-telemetry/opentelemetry-specification

pellared · 2025-02-10T10:46:50Z

Describe (in form of an appendix) how log record filtering, fan-out (multiple isolated pipelines), etc can be done with the current log processors design.

I want to have this documented the following reasons:

For specification contributors, to show that we do not need a second type of "chaining" log record processors. Providing new types would only increase the complexity of the design and confusion for the users.
For maintainers, the examples could be used as inspiration for a language documentation for advanced scenarios.
(minor) In future, it might facilitate reviewing Add Enabled to LogRecordProcessor #4363 as we could showcase its usage in advanced processing pipelines. This would help discussing its pros and cons of the design.

This documents the patterns that our users are already using like Decorator and Composite (because there is no other clean way to do it).

specification/logs/supplementary-guidelines.md

Co-authored-by: Cijo Thomas <cithomas@microsoft.com>

specification/logs/supplementary-guidelines.md

specification/logs/sdk.md

CHANGELOG.md

specification/logs/supplementary-guidelines.md

Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>

specification/logs/sdk.md

reyang · 2025-02-22T00:33:47Z

specification/logs/supplementary-guidelines.md

    + [Implicit Context Injection](#implicit-context-injection)
    + [Explicit Context Injection](#explicit-context-injection)
+  * [Advanced Processing](#advanced-processing)
+    + [Altering](#altering)


There could be other scenarios such as aggregation (e.g. logs to metrics conversion), sampling, etc. Curious which scenarios do we want to cover vs. not?

March 2025 Release. ## v1.43.0 (2025-03-11) ### Traces - Clarify STDOUT exporter format is unspecified. ([#4418](#4418)) ### Metrics - Clarify STDOUT exporter format is unspecified. ([#4418](#4418)) ### Logs - Clarify that it is allowed to directly use Logs API. ([#4438](#4438)) - Clarify STDOUT exporter format is unspecified. ([#4418](#4418)) ### Supplementary Guidelines - Add Advanced Processing to Logs Supplementary Guidelines. ([#4407](#4407)) --------- Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>

Fixes #4363 Towards #4208 (uses Severity Level passed via Logger.Enabled) Towards stabilization of OpenTelemetry Go Logs API and SDK. ## Use cases Below are some use cases where the new functionality can be used: 1. Bridge features like `LogLevelEnabled` in log bridge/appender implementations. This is needed for **all** (but one) currently supported log bridges in OTel Go Contrib. 2. Configure a minimum log severity level for a certain log processor. 3. Filter out log and event records when they are inside a span that has been sampled out (span is valid and has sampled flag of `false`). 4. **Efficiently** support high-performance logging destination like [Linux user_events](https://docs.kernel.org/trace/user_events.html) and [ETW (Event Tracing for Windows)](https://learn.microsoft.com/windows/win32/etw/about-event-tracing). 5. Bridge Logs API to a language-specific logging library (the other way than usual). ## Changes Add `Enabled` opt-in operation to the `LogRecordProcessor`. I created an OTEP first which was a great for having a lot of discussions and evaluations of different proposals: - #4290 Most importantly from #4290 (comment): > Among Go SIG we were evaluating a few times an alternative to provide some new "filter" abstraction which is decoupled from the "processor". However, we faced more issues than benefits going this route (some if this is described here, but there were more issues: open-telemetry/opentelemetry-go#5825 (comment) . With the current opt-in `Processor.Enabled` we faced less issues so far. > We also do not want to replicate all features from the logging libraries. If someone prefer the log4j (or other) filter design then someone can always use a bridge and use log4j for filtering. `Enabled` callback hook is the simplest design (yet very flexible) which makes it easy to implement in the SDKs. This design is inspired from the design of the two most popular Go structured logging libraries: https://pkg.go.dev/log/slog (standard library) and https://pkg.go.dev/go.uber.org/zap. > > It is worth to adding that Rust design is similar and it also has an `Enabled` hook. See #4363 (comment). Basically we want to add something like https://docs.rs/log/latest/log/trait.Log.html#tymethod.enabled to the `LogRecordProcessor` and allow users to implement `Enabled` in the way that it will meet their requirements. > > I also want to call out form https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0265-event-vision.md#open-questions: > > > How to support routing logs from the Logs API to a language-specific logging library > > To support this we would need a log record processor which bridges the Logs API calls to given logging library. For such case we would need an `Enabled` hook in `Processor` to efficiently bridge `Logger.Enabled` calls. A filterer design would not satisfy such use case. I decided to name the new operation `Enabled` as: 1. this name is already used in logging libraries in many languages: #4439 (comment) 2. it matches the name of the API call (for all trace, metrics and logs APIs). I was also considering `OnEnabled` to have the same pattern as for `Emit` and `OnEmit`. However, we already have `ForceFlush` and `Shutdown` which does not follow this pattern so I preferred to keep the simple `Enabled` name. For `OnEmit` I could also imagine `OnEmitted` (or `OnEmitting`) which does something after (or just before like we have `OnEnding` in `SpanProcessor`) `OnEmit` on all registered processors were called. Yet, I do not imagine something similar for `Enabled` as calling `Enabled` should not have any side-effects. Therefore, I decided to name it `Enabled`. I want to highlight that a processor cannot assume `Enabled` was called before `OnEmit`, because of the following reasons: 1. **Backward compatibility** – Existing processors may already perform filtering without relying on `Enabled`. For example: [Add Advanced Processing to Logs Supplementary Guidelines #4407](#4407). 2. **Self-sufficiency of `OnEmit`** – Since `Enabled` is optional, `OnEmit` should be able to handle filtering independently. A processor filtering events should do so in `OnEmit`, not just in `Enabled`. 3. **Greater flexibility** – Some processors, such as the ETW processor, don’t benefit from redundant filtering. ETW already filters out events internally, making an additional check unnecessary. 4. **Performance considerations** – Calling `Enabled` from `OnEmit` introduces overhead, as it requires converting `OnEmit` parameters to match `Enabled`'s expected input. 5. **Avoiding fragile assumptions** – Enforcing constraints that the compiler cannot validate increases the risk of introducing bugs. This feature is already implemented in OpenTelemetry Go: - open-telemetry/opentelemetry-go#6317 We have one processor in Contrib which takes advantage of this functionality: - https://pkg.go.dev/go.opentelemetry.io/contrib/processors/minsev This feautre (however with some differences) is also avaiable in OTel Rust; #4363 (comment): > OTel Rust also has this capability. Here's an example where it is leveraged to improve performance by dropping unwanted log early. https://github.com/open-telemetry/opentelemetry-rust/blob/88cae2cf7d0ff54a042d281a0df20f096d18bf82/opentelemetry-appender-tracing/benches/logs.rs#L78-L85 --------- Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> Co-authored-by: Sam Xie <sam@samxie.me>

Add Complex Processing to Logs Supplementary Guidelines

0e1e016

pellared self-assigned this Feb 10, 2025

pellared added the spec:logs Related to the specification/logs directory label Feb 10, 2025

pellared changed the title ~~Add Complex Processing to Logs Supplementary Guidelines~~ [WIP] Add Complex Processing to Logs Supplementary Guidelines Feb 10, 2025

pellared added 5 commits February 10, 2025 16:55

Content

c471e42

Remove unecessary

eebacd3

More use cases

e653f24

Add changelog entry

8ca7841

Merge branch 'main' into complex-log-processing

dd9c867

pellared changed the title ~~[WIP] Add Complex Processing to Logs Supplementary Guidelines~~ Add Complex Processing to Logs Supplementary Guidelines Feb 10, 2025

pellared added 2 commits February 10, 2025 17:11

markdownlint: inline ignore no-hard-tabs

75d9aa2

Merge branch 'main' into complex-log-processing

a5b4dd7

pellared marked this pull request as ready for review February 10, 2025 16:45

pellared requested review from a team February 10, 2025 16:45

Update supplementary-guidelines.md

fa01c47

cijothomas reviewed Feb 10, 2025

View reviewed changes

specification/logs/supplementary-guidelines.md Outdated Show resolved Hide resolved

Update specification/logs/supplementary-guidelines.md

5c96c61

Co-authored-by: Cijo Thomas <cithomas@microsoft.com>

pellared requested a review from cijothomas February 10, 2025 17:37

Update supplementary-guidelines.md

f1145c7

cijothomas reviewed Feb 10, 2025

View reviewed changes

specification/logs/supplementary-guidelines.md Show resolved Hide resolved

cijothomas reviewed Feb 10, 2025

View reviewed changes

specification/logs/supplementary-guidelines.md Show resolved Hide resolved

lmolkova reviewed Feb 10, 2025

View reviewed changes

pellared added 7 commits February 11, 2025 13:58

Address feedback

545dc53

Merge branch 'main' into complex-log-processing

b2a2459

Add note

b7d5f07

Make the Go snippets to compile

3add16d

Add RedactTokensProcessor

98224d0

Add setup example

5595830

Add comments

fd89f0b

Merge branch 'main' into complex-log-processing

834cc21

MrAlias approved these changes Feb 13, 2025

View reviewed changes