From 4c5f4c717c7cdde9b5cc1c657b18d8305d17a918 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Mar 2025 10:05:36 +0100 Subject: [PATCH 01/14] Define LogRecordProcessor.Enabled operation --- specification/logs/sdk.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 971b9795ed7..0186748c710 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -24,6 +24,7 @@ - [LogRecordProcessor](#logrecordprocessor) * [LogRecordProcessor operations](#logrecordprocessor-operations) + [OnEmit](#onemit) + + [Enabled](#enabled-1) + [ShutDown](#shutdown) + [ForceFlush](#forceflush-1) * [Built-in processors](#built-in-processors) @@ -198,7 +199,9 @@ It consists of the following parameters: `Enabled` MUST return `false` when: - there are no registered [`LogRecordProcessors`](#logrecordprocessor), -- `Logger` is disabled ([`LoggerConfig.disabled`](#loggerconfig) is `true`). +- `Logger` is disabled ([`LoggerConfig.disabled`](#loggerconfig) is `true`), +- all registered `LogRecordProcessors` implement [`Enabled`](#enabled-1), + and a call to `Enabled` on each of them returns `false`. Otherwise, it SHOULD return `true`. It MAY return `false` to support additional optimizations and features. @@ -345,6 +348,37 @@ A `LogRecordProcessor` may freely modify `logRecord` for the duration of the `OnEmit` call. If `logRecord` is needed after `OnEmit` returns (i.e. for asynchronous processing) only reads are permitted. +#### Enabled + +`Enabled` is an opt-in operation that a `LogRecordProcessor` may implement +in order to support filtering via [`Logger.Enabled`](api.md#enabled). + +**Parameters:** + +* [Resource](./data-model.md#field-resource) associated with the `LoggerProvider` +* [Instrumentation Scope](./data-model.md#field-instrumentationscope) associated + with the `Logger` +* [Context](../context/README.md) explicitly passed by the caller or the current + Context +* [Severity Number](./data-model.md#field-severitynumber) passed by the caller + +**Returns:** `Boolean` + +Any modifications to parameters inside `Enabled` MUST NOT be propagated to the +caller. Parameters are immutable or passed by value. + +An implementation should default to returning `true` for an indeterminate +state, but may return `false` if valid reasons in particular circumstances +exist (e.g. performance). + +`LogRecordProcessor` implementations that choose to support this operation are +expected to re-evaluate the [ReadWriteLogRecord](#readwritelogrecord) passed to +[`OnEmit`](#onemit). It is not expected that the caller to `OnEmit` will use the +functionality from this operation prior to calling `OnEmit`. + +This operation is usually called synchronously, therefore it should not block +or throw exceptions. + #### ShutDown Shuts down the processor. Called when the SDK is shut down. This is an From 8b9bdd5214ad2b39dfd4d1bcf40215d60eac5863 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Mar 2025 10:07:11 +0100 Subject: [PATCH 02/14] Add changelog entry --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5aa8bbab53..18d8d6042b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ release. - Clarify STDOUT exporter format is unspecified. ([#4418](https://github.com/open-telemetry/opentelemetry-specification/pull/4418)) +- Add `Enabled` opt-in operation to the `LogRecordProcessor`. + ([#TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/TODO)) ### Baggage From f80e91362b3e38e7294bb95451e1c2014d4becc8 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Mar 2025 10:09:00 +0100 Subject: [PATCH 03/14] Update changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 18d8d6042b6..dd14cd02eba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,7 +24,7 @@ release. - Clarify STDOUT exporter format is unspecified. ([#4418](https://github.com/open-telemetry/opentelemetry-specification/pull/4418)) - Add `Enabled` opt-in operation to the `LogRecordProcessor`. - ([#TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/TODO)) + ([#4439](https://github.com/open-telemetry/opentelemetry-specification/pull/4439)) ### Baggage From 7930471b9467398d17c64d5fc4a95e11a8adbfa1 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Mar 2025 10:34:07 +0100 Subject: [PATCH 04/14] Update Advanced Processing examples --- .../logs/supplementary-guidelines.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/specification/logs/supplementary-guidelines.md b/specification/logs/supplementary-guidelines.md index 8779536d78c..deeeb044700 100644 --- a/specification/logs/supplementary-guidelines.md +++ b/specification/logs/supplementary-guidelines.md @@ -203,6 +203,19 @@ func (p *SeverityProcessor) OnEmit(ctx context.Context, record *sdklog.Record) e } return p.Processor.OnEmit(ctx, record) } + +// Enabled returns false if the severity is lower than p.Min. +func (p *SeverityProcessor) Enabled(ctx context.Context, param sdklog.EnabledParameters) bool { + sev := param.Severity + if sev != log.SeverityUndefined && sev < p.Min { + return false + } + if fp, ok := p.Processor.(sdklog.FilterProcessor); ok { + // The wrapped processor is also a filtering processor. + return p.Processor.Enabled(ctx, param) + } + return true +} ``` > [!NOTE] @@ -242,6 +255,29 @@ func (p *IsolatedProcessor) OnEmit(ctx context.Context, record *log.Record) erro } return rErr } + +// Enabled honors Enabled of the wrapped processors. +func (p *IsolatedProcessor) Enabled(ctx context.Context, param sdklog.EnabledParameters) bool { + fltrProcessors := make([]sdklog.FilterProcessor, len(p.Processors)) + for i, proc := range p.Processors { + fp, ok := proc.(sdklog.FilterProcessor) + if !ok { + // Processor not implementing Enabled. + // We asume it will be processed. + return true + } + fltrProcessors[i] = fp + } + + for _, proc := range fltrProcessors { + if proc.Enabled(ctx, param) { + // At least one Processor will process the Record. + return true + } + } + // No processor will process the record. + return false +} ``` #### Routing @@ -271,6 +307,29 @@ func (p *LogEventRouteProcessor) OnEmit(ctx context.Context, record *log.Record) } return p.LogProcessor.OnEmit(ctx, record) } + +// Enabled honors Enabled of the wrapped processors. +func (p *LogEventRouteProcessor) Enabled(ctx context.Context, param sdklog.EnabledParameters) bool { + fp1, ok := p.EventProcessor.(sdklog.FilterProcessor) + if !ok { + // Processor not implementing Enabled. + return true + } + fp2, ok := p.LogProcessor.(sdklog.FilterProcessor) + if !ok { + // Processor not implementing Enabled. + return true + } + + if fp1.Enabled(ctx, param) { + return true + } + if fp2.Enabled(ctx, param) { + return true + } + // No processor will process the record. + return false +} ``` #### Setup From 64782aba308d061278db009c2734d7458c0cdbed Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Mar 2025 10:36:35 +0100 Subject: [PATCH 05/14] Update compliance matric --- spec-compliance-matrix.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index c67da6ed397..9875b9f12ce 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -203,6 +203,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t | SimpleLogRecordProcessor | | | + | | + | | | + | | + | | | | BatchLogRecordProcessor | | | + | | + | | | + | | + | | | | Can plug custom LogRecordProcessor | | | + | | + | | | + | | + | | | +| Opt-in LogRecordProcessor.Enabled | | | + | | + | | | + | | + | | | | OTLP/gRPC exporter | | | + | | + | | | + | | + | + | | | OTLP/HTTP exporter | | | + | | + | | | + | | + | + | | | OTLP File exporter | | | - | | - | | | | | + | - | | From 6292fb7bf1ac90dd169fad2a741c618d978b911b Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Mar 2025 10:38:11 +0100 Subject: [PATCH 06/14] Fix typo --- specification/logs/supplementary-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/supplementary-guidelines.md b/specification/logs/supplementary-guidelines.md index deeeb044700..67346488ad6 100644 --- a/specification/logs/supplementary-guidelines.md +++ b/specification/logs/supplementary-guidelines.md @@ -263,7 +263,7 @@ func (p *IsolatedProcessor) Enabled(ctx context.Context, param sdklog.EnabledPar fp, ok := proc.(sdklog.FilterProcessor) if !ok { // Processor not implementing Enabled. - // We asume it will be processed. + // We assume it will be processed. return true } fltrProcessors[i] = fp From 53f825f6f04861cc24c0e1d8b81c7e0e5a0002fd Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Mar 2025 10:52:45 +0100 Subject: [PATCH 07/14] Add development status label --- specification/logs/sdk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 0186748c710..4e646661a8a 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -350,6 +350,8 @@ asynchronous processing) only reads are permitted. #### Enabled +**Status**: [Development](../document-status.md) + `Enabled` is an opt-in operation that a `LogRecordProcessor` may implement in order to support filtering via [`Logger.Enabled`](api.md#enabled). From 4ed48971d1b96114df5c4f8db6a19abc9ce6475e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 4 Mar 2025 17:50:33 +0100 Subject: [PATCH 08/14] Update specification/logs/sdk.md Co-authored-by: Tyler Yahn --- specification/logs/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 4e646661a8a..8e948424635 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -352,7 +352,7 @@ asynchronous processing) only reads are permitted. **Status**: [Development](../document-status.md) -`Enabled` is an opt-in operation that a `LogRecordProcessor` may implement +`Enabled` is an opt-in operation that a `LogRecordProcessor` MAY implement in order to support filtering via [`Logger.Enabled`](api.md#enabled). **Parameters:** From 2ff3f5a2870cab1431bbe20f99bb2e490fb2f352 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 5 Mar 2025 08:43:06 +0100 Subject: [PATCH 09/14] Update specification/logs/sdk.md --- specification/logs/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 8e948424635..29af2ab7074 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -352,7 +352,7 @@ asynchronous processing) only reads are permitted. **Status**: [Development](../document-status.md) -`Enabled` is an opt-in operation that a `LogRecordProcessor` MAY implement +`Enabled` is an operation that a `LogRecordProcessor` MAY implement in order to support filtering via [`Logger.Enabled`](api.md#enabled). **Parameters:** From df9ebb1014156de3254bfb80fa979b82f6d2fcbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 5 Mar 2025 08:43:40 +0100 Subject: [PATCH 10/14] Update specification/logs/sdk.md --- specification/logs/sdk.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 29af2ab7074..55057c40b5c 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -357,7 +357,6 @@ in order to support filtering via [`Logger.Enabled`](api.md#enabled). **Parameters:** -* [Resource](./data-model.md#field-resource) associated with the `LoggerProvider` * [Instrumentation Scope](./data-model.md#field-instrumentationscope) associated with the `Logger` * [Context](../context/README.md) explicitly passed by the caller or the current From 25b9a4d57063427660c515b5c9698cab613ce3a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 5 Mar 2025 08:44:32 +0100 Subject: [PATCH 11/14] Update spec-compliance-matrix.md --- spec-compliance-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 9875b9f12ce..532ea02e452 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -203,7 +203,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t | SimpleLogRecordProcessor | | | + | | + | | | + | | + | | | | BatchLogRecordProcessor | | | + | | + | | | + | | + | | | | Can plug custom LogRecordProcessor | | | + | | + | | | + | | + | | | -| Opt-in LogRecordProcessor.Enabled | | | + | | + | | | + | | + | | | +| LogRecordProcessor.Enabled | | | + | | + | | | + | | + | | | | OTLP/gRPC exporter | | | + | | + | | | + | | + | + | | | OTLP/HTTP exporter | | | + | | + | | | + | | + | + | | | OTLP File exporter | | | - | | - | | | | | + | - | | From 5ae676182656616c6dd9d5271dfd293d2449155a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 11 Mar 2025 00:45:36 +0100 Subject: [PATCH 12/14] Update specification/logs/sdk.md Co-authored-by: Sam Xie --- specification/logs/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 55057c40b5c..7dff1519317 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -357,10 +357,10 @@ in order to support filtering via [`Logger.Enabled`](api.md#enabled). **Parameters:** -* [Instrumentation Scope](./data-model.md#field-instrumentationscope) associated - with the `Logger` * [Context](../context/README.md) explicitly passed by the caller or the current Context +* [Instrumentation Scope](./data-model.md#field-instrumentationscope) associated + with the `Logger` * [Severity Number](./data-model.md#field-severitynumber) passed by the caller **Returns:** `Boolean` From 4f60c059b566eac83c490f35290eae3a4ed644ec Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 18 Mar 2025 09:03:28 +0100 Subject: [PATCH 13/14] More details on LogRecordProcessor implementation --- specification/logs/sdk.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 7dff1519317..0ee77311f96 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -365,21 +365,29 @@ in order to support filtering via [`Logger.Enabled`](api.md#enabled). **Returns:** `Boolean` +An implementation should return `false` if a `LogRecord` (if ever created) +is supposed to be filtered out for the given parameters. +It should default to returning `true` for any indeterminate state, for example, +when awaiting configuration. + Any modifications to parameters inside `Enabled` MUST NOT be propagated to the caller. Parameters are immutable or passed by value. -An implementation should default to returning `true` for an indeterminate -state, but may return `false` if valid reasons in particular circumstances -exist (e.g. performance). - -`LogRecordProcessor` implementations that choose to support this operation are -expected to re-evaluate the [ReadWriteLogRecord](#readwritelogrecord) passed to -[`OnEmit`](#onemit). It is not expected that the caller to `OnEmit` will use the -functionality from this operation prior to calling `OnEmit`. - This operation is usually called synchronously, therefore it should not block or throw exceptions. +`LogRecordProcessor` implementations responsible for filtering and supporting +the `Enable` operation should ensure that [`OnEmit`](#onemit) handles filtering +independently. API users cannot be expected to call [`Enabled`](api.md#enabled) +before invoking [`Emit a LogRecord`](api.md#emit-a-logrecord). +Moreover, the filtering logic in `OnEmit` and `Enabled` may differ. + +`LogRecordProcessor` implementations that wrap other `LogRecordProcessor` +(which may perform filtering) can implement `Enabled` and delegate to +the wrapped processor’s `Enabled`, if available. However, the `OnEmit` +implementation of such processors should never call the wrapped processor’s +`Enabled`, as `OnEmit` is responsible for handling filtering independently. + #### ShutDown Shuts down the processor. Called when the SDK is shut down. This is an From c0a6a34b22b71cc46076915891352bf3abdb47ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 25 Mar 2025 09:11:02 +0100 Subject: [PATCH 14/14] Update spec-compliance-matrix.md --- spec-compliance-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 532ea02e452..bf5eca600af 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -203,7 +203,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t | SimpleLogRecordProcessor | | | + | | + | | | + | | + | | | | BatchLogRecordProcessor | | | + | | + | | | + | | + | | | | Can plug custom LogRecordProcessor | | | + | | + | | | + | | + | | | -| LogRecordProcessor.Enabled | | | + | | + | | | + | | + | | | +| LogRecordProcessor.Enabled | X | + | | | | | | | | | | | | OTLP/gRPC exporter | | | + | | + | | | + | | + | + | | | OTLP/HTTP exporter | | | + | | + | | | + | | + | + | | | OTLP File exporter | | | - | | - | | | | | + | - | |