-
Notifications
You must be signed in to change notification settings - Fork 1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move
log.Processor.Enabled
to independent FilterProcessor
interfa…
…ced type (#5692) Closes #5425 Our current log `Processor` interface contains more functionality than the [OTel spec](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md#logrecordprocessor-operations). The additional functionality allows processors to report back to the API if a Record should be constructed and emitted or not, which is quite helpful[^1][^2][^3][^4][^5]. This removes the `Enabled` method from the `Processor` type. It adds this functionality a new optional and experimental `FilterProcessor` interface type. The logger and provider are updated to check for this optional interface to be implemented with the configured processors and uses them to back the `Logger.Enabled` method, preserving existing functionality. By making this change: - The `Processor` interface is now compliant with the OTel spec and does not contain any additional unspecified behavior. - All `Processor` implementations are no longer required to implement an `Enabled` method. The default, when they do not implement this method, is to assume they are enabled. ### Benchmark ```terminal goos: linux goarch: amd64 pkg: go.opentelemetry.io/otel/sdk/log cpu: Intel(R) Core(TM) i7-8550U CPU @ 1.80GHz │ old.txt │ new7.txt │ │ sec/op │ sec/op vs base │ LoggerEnabled-8 133.30n ± 3% 32.36n ± 3% -75.72% (p=0.000 n=10) │ old.txt │ new7.txt │ │ B/op │ B/op vs base │ LoggerEnabled-8 0.000 ± 0% 0.000 ± 0% ~ (p=1.000 n=10) ¹ ¹ all samples are equal │ old.txt │ new7.txt │ │ allocs/op │ allocs/op vs base │ LoggerEnabled-8 0.000 ± 0% 0.000 ± 0% ~ (p=1.000 n=10) ¹ ¹ all samples are equal ``` This is a significant performance improvement due to the `Record` no longer being converted from the API version to the SDK version. [^1]: https://pkg.go.dev/go.opentelemetry.io/contrib/processors/minsev [^2]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/log#BatchProcessor.Enabled [^3]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/log#SimpleProcessor.Enabled [^4]: https://github.com/open-telemetry/opentelemetry-go-contrib/blob/af75717ac4fb3ba13eaea83b88301723122060cf/bridges/otelslog/handler.go#L206-L211 [^5]: https://github.com/open-telemetry/opentelemetry-go-contrib/blob/d0309ddd8c5714af1cd9dbe8b39b7e8f10485679/bridges/otelzap/core.go#L142-L146 --------- Co-authored-by: Robert Pająk <pellared@hotmail.com> Co-authored-by: Sam Xie <sam@samxie.me>
- Loading branch information
1 parent
fe6c67e
commit 002c0a4
Showing
14 changed files
with
197 additions
and
62 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
# Experimental Features | ||
|
||
The Logs SDK contains features that have not yet stabilized. | ||
These features are added to the OpenTelemetry Go Logs SDK prior to stabilization so that users can start experimenting with them and provide feedback. | ||
|
||
These feature may change in backwards incompatible ways as feedback is applied. | ||
See the [Compatibility and Stability](#compatibility-and-stability) section for more information. | ||
|
||
## Features | ||
|
||
- [Filter Processors](#filter-processor) | ||
|
||
### Filter Processor | ||
|
||
Users of logging libraries often want to know if a log `Record` will be processed or dropped before they perform complex operations to construct the `Record`. | ||
The [`Logger`] in the Logs Bridge API provides the `Enabled` method for just this use-case. | ||
In order for the Logs Bridge SDK to effectively implement this API, it needs to be known if the registered [`Processor`]s are enabled for the `Record` within a context. | ||
A [`Processor`] that knows, and can identify, what `Record` it will process or drop when it is passed to `OnEmit` can communicate this to the SDK `Logger` by implementing the `FilterProcessor`. | ||
|
||
By default, the SDK `Logger.Enabled` will return true when called. | ||
Only if all the registered [`Processor`]s implement `FilterProcessor` and they all return `false` will `Logger.Enabled` return `false`. | ||
|
||
See the [`minsev`] [`Processor`] for an example use-case. | ||
It is used to filter `Record`s out that a have a `Severity` below a threshold. | ||
|
||
[`Logger`]: https://pkg.go.dev/go.opentelemetry.io/otel/log#Logger | ||
[`Processor`]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/log#Processor | ||
[`minsev`]: https://pkg.go.dev/go.opentelemetry.io/contrib/processors/minsev | ||
|
||
## Compatibility and Stability | ||
|
||
Experimental features do not fall within the scope of the OpenTelemetry Go versioning and stability [policy](../../../../VERSIONING.md). | ||
These features may be removed or modified in successive version releases, including patch versions. | ||
|
||
When an experimental feature is promoted to a stable feature, a migration path will be included in the changelog entry of the release. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,46 @@ | ||
// Copyright The OpenTelemetry Authors | ||
// SPDX-License-Identifier: Apache-2.0 | ||
|
||
// Package x contains support for Logs SDK experimental features. | ||
package x // import "go.opentelemetry.io/otel/sdk/log/internal/x" | ||
|
||
import ( | ||
"context" | ||
|
||
"go.opentelemetry.io/otel/log" | ||
) | ||
|
||
// FilterProcessor is a [Processor] that knows, and can identify, what | ||
// [log.Record] it will process or drop when it is passed to OnEmit. | ||
// | ||
// This is useful for users of logging libraries that want to know if a [log.Record] | ||
// will be processed or dropped before they perform complex operations to | ||
// construct the [log.Record]. | ||
// | ||
// [Processor] implementations that choose to support this by satisfying this | ||
// interface are expected to re-evaluate the [log.Record]s passed to OnEmit, it is | ||
// not expected that the caller to OnEmit will use the functionality from this | ||
// interface prior to calling OnEmit. | ||
// | ||
// This should only be implemented for [Processor]s that can make reliable | ||
// enough determination of this prior to processing a [log.Record] and where | ||
// the result is dynamic. | ||
// | ||
// [Processor]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/log#Processor | ||
type FilterProcessor interface { | ||
// Enabled returns whether the Processor will process for the given context | ||
// and record. | ||
// | ||
// The passed record is likely to be a partial record with only the | ||
// bridge-relevant information being provided (e.g a record with only the | ||
// Severity set). If a Logger needs more information than is provided, it | ||
// is said to be in an indeterminate state (see below). | ||
// | ||
// The returned value will be true when the Processor will process for the | ||
// provided context and record, and will be false if the Processor will not | ||
// process. An implementation should default to returning true for an | ||
// indeterminate state. | ||
// | ||
// Implementations should not modify the record. | ||
Enabled(ctx context.Context, record log.Record) bool | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.