From f3aeadbd152ce50c4d2cc9bc94902613bb49cffd Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Tue, 28 May 2024 09:24:07 -0700 Subject: [PATCH] Add Enabled method to Logger (#4020) --- CHANGELOG.md | 3 +++ spec-compliance-matrix.md | 1 + specification/logs/bridge-api.md | 26 +++++++++++++++++++++++++- 3 files changed, 29 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 63382fe20e1..653d45d89d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ release. ### Logs +- Add the experimental `Enabled` API to the `Logger`. + ([#4020](https://github.com/open-telemetry/opentelemetry-specification/pull/4020)) + ### Events - Add specification for EventLogger and EventLoggerProvider diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index c13a51792c5..9badcf77d6f 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -191,6 +191,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t | LoggerProvider.Shutdown | | | + | | | | | + | | | - | | | LoggerProvider.ForceFlush | | | + | | | | | + | | | - | | | Logger.Emit(LogRecord) | | | + | | | | | + | | + | - | | +| Logger.Enabled | X | + | | | | | | | + | + | | | | SimpleLogRecordProcessor | | | + | | | | | + | | + | | | | BatchLogRecordProcessor | | | + | | | | | + | | + | | | | Can plug custom LogRecordProcessor | | | + | | | | | + | | + | | | diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index ef310f9c53e..001bd00d345 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -1,6 +1,6 @@ # Logs Bridge API -**Status**: [Stable](../document-status.md) +**Status**: [Stable](../document-status.md), except where otherwise specified
Table of Contents @@ -15,6 +15,7 @@ - [Logger](#logger) * [Logger operations](#logger-operations) + [Emit a LogRecord](#emit-a-logrecord) + + [Enabled](#enabled) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -108,6 +109,10 @@ The `Logger` MUST provide functions to: - Emit a `LogRecord` +The `Logger` SHOULD provide functions to: + +- Report if `Enabled` for a `LogRecord` + #### Emit a LogRecord The effect of calling this API is to emit a `LogRecord` to the processing pipeline. @@ -127,6 +132,25 @@ The API MUST accept the following parameters: All parameters are optional. +#### Enabled + +**Status**: [Experimental](../document-status.md) + +To help users avoid performing computationally expensive operations when +generating a `LogRecord`, a `Logger` SHOULD provide this `Enabled` API. + +There are currently no required parameters for this API. Parameters can be +added in the future, therefore, the API MUST be structured in a way for +parameters to be added. + +This API MUST return a language idiomatic boolean type. A returned value of +`true` means logging is enabled for the provided arguments, and a returned +value of `false` means the logging is disabled for the provided arguments. + +The returned value is not always static, it can change over time. The API +SHOULD be documented that Logs Bridge API developers needs to call this API each time they generate +a `LogRecord` to ensure they have the most up-to-date response. + ## Optional and required parameters The operations defined include various parameters, some of which are marked