Add Enabled method to Logger (open-telemetry#4020)

MrAlias · May 28, 2024 · f3aeadb · f3aeadb
1 parent 7c19b61
commit f3aeadb
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 1 deletion.
diff --git 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
@@ -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
@@ -1,6 +1,6 @@
 # Logs Bridge API
 
-**Status**: [Stable](../document-status.md)
+**Status**: [Stable](../document-status.md), except where otherwise specified
 
 <details>
 <summary>Table of Contents</summary>
@@ -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