002c0a4c03
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]:af75717ac4/bridges/otelslog/handler.go (L206-L211)[^5]:d0309ddd8c/bridges/otelzap/core.go (L142-L146)--------- Co-authored-by: Robert Pająk <pellared@hotmail.com> Co-authored-by: Sam Xie <sam@samxie.me>
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 section for more information.
Features
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 Processors 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 Processors 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 Records out that a have a Severity below a threshold.
Compatibility and Stability
Experimental features do not fall within the scope of the OpenTelemetry Go versioning and stability policy. 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.