From 770bc0563d2233eb4dfb5f63db4471dac1b9aa4b Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 29 Apr 2024 12:39:56 -0700 Subject: [PATCH 01/11] Add Enabled section to Logger --- specification/logs/bridge-api.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index ef310f9c53e..ee998ece6a5 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -108,6 +108,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 +131,30 @@ The API MUST accept the following parameters: All parameters are optional. +#### Enabled + +To help users avoid performing computationally expensive operations when +generating a `LogRecord`, a `Logger` SHOULD provide this `Enabled` API. + +At a minimum, the API MUST accept the following parameters: + +- [Context](../context/README.md) (optional): This is the Context associated + with the `LogRecord`. The API MAY implicitly use the current Context as a + default behavior. +- [Severity Number](./data-model.md#field-severitynumber) + +Users of a language implementation community can have specific needs when using +this API. Therefore, additional parameters MAY be accepted. + +This API MUST return a language idiomatic boolean type. + +The returned value MUST be `true` when logging is enabled for the provided +arguments. The returned value can be `true` or `false` when logging is disabled +for the provided arguments. The ambiguity when disabled allows implementation +that want to optimize memory or handle indeterminable states the flexibility +they need. If an implementation does not need this flexibility, it SHOULD +return `false` when logging is disabled for the provided arguments. + ## Optional and required parameters The operations defined include various parameters, some of which are marked From f328d91542a339570d1cfbe30ba6cebf1538ad37 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 29 Apr 2024 12:40:42 -0700 Subject: [PATCH 02/11] Generate TOC --- specification/logs/bridge-api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index ee998ece6a5..f21344dc048 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -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) From 3b507e5213649298a508bf019fc0056fcb0e3791 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 29 Apr 2024 12:48:47 -0700 Subject: [PATCH 03/11] Add changelog entry --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 13e5b73e50b..6e8a82cdadd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ release. ### Logs +- Add the `Enabled` API to the `Logger`. + ([#4020](https://github.com/open-telemetry/opentelemetry-specification/pull/4020)) + ### Events ### Resource From de847199b340601dbc17b7deaeb499f82ca7396b Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 29 Apr 2024 12:50:44 -0700 Subject: [PATCH 04/11] Update the spec compliance matrix --- spec-compliance-matrix.md | 1 + 1 file changed, 1 insertion(+) 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 | | | + | | | | | + | | + | | | From 20868489a83e69b3949a5736c89c2e0180979548 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 29 Apr 2024 12:52:48 -0700 Subject: [PATCH 05/11] Mark Enabled section as Experimental --- CHANGELOG.md | 2 +- specification/logs/bridge-api.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e8a82cdadd..96c1b020858 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,7 @@ release. ### Logs -- Add the `Enabled` API to the `Logger`. +- Add the experimental `Enabled` API to the `Logger`. ([#4020](https://github.com/open-telemetry/opentelemetry-specification/pull/4020)) ### Events diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index f21344dc048..01cc8e63114 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 @@ -134,6 +134,8 @@ 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. From f924735562ccc939e8b791aea2b1d35039620bd8 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 29 Apr 2024 13:45:06 -0700 Subject: [PATCH 06/11] Recommend doc for API about dynamic response --- specification/logs/bridge-api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 01cc8e63114..c233fc23f0f 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -158,6 +158,10 @@ that want to optimize memory or handle indeterminable states the flexibility they need. If an implementation does not need this flexibility, it SHOULD return `false` when 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 users 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 From 19ade6db74d62bd139f3e81f8497342f2da393c4 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Fri, 10 May 2024 08:30:32 -0700 Subject: [PATCH 07/11] Replace parameters requirement Do not specify required parameters, but explain they can be added in the future. --- specification/logs/bridge-api.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index c233fc23f0f..7bdca2eb5ef 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -139,15 +139,9 @@ All parameters are optional. To help users avoid performing computationally expensive operations when generating a `LogRecord`, a `Logger` SHOULD provide this `Enabled` API. -At a minimum, the API MUST accept the following parameters: - -- [Context](../context/README.md) (optional): This is the Context associated - with the `LogRecord`. The API MAY implicitly use the current Context as a - default behavior. -- [Severity Number](./data-model.md#field-severitynumber) - -Users of a language implementation community can have specific needs when using -this API. Therefore, additional parameters MAY be accepted. +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. From b646ca237fbf2f53dfc74745e11ca6bd9292eac0 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Fri, 10 May 2024 08:37:08 -0700 Subject: [PATCH 08/11] Fix lint --- specification/logs/bridge-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 7bdca2eb5ef..09fbec827a3 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -141,7 +141,7 @@ 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. +parameters to be added. This API MUST return a language idiomatic boolean type. From aa6b297a3b6dc6fa4cefac7af4ce788b5fff79a6 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Tue, 21 May 2024 08:43:43 -0700 Subject: [PATCH 09/11] Redefine the return value Clarify the true/false expectation and add optional stale value return. --- specification/logs/bridge-api.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 09fbec827a3..e3ccf26ce76 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -145,12 +145,9 @@ parameters to be added. This API MUST return a language idiomatic boolean type. -The returned value MUST be `true` when logging is enabled for the provided -arguments. The returned value can be `true` or `false` when logging is disabled -for the provided arguments. The ambiguity when disabled allows implementation -that want to optimize memory or handle indeterminable states the flexibility -they need. If an implementation does not need this flexibility, it SHOULD -return `false` when logging is disabled for the provided arguments. +Implementations of this API SHALL return `true` when logging is enabled or +`false` when logging is disabled for the provided arguments. Implementations +designed for performance that cache the logging state MAY return stale values. The returned value is not always static, it can change over time. The API SHOULD be documented that users needs to call this API each time they generate From d757b5486df1ac731b0c704b3ba5436c7eb7ae34 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Thu, 23 May 2024 08:22:12 -0700 Subject: [PATCH 10/11] Remove spec for implementation return value Leave the return value implementation for implementations specification. --- specification/logs/bridge-api.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index e3ccf26ce76..552b704b540 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -143,11 +143,9 @@ 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. - -Implementations of this API SHALL return `true` when logging is enabled or -`false` when logging is disabled for the provided arguments. Implementations -designed for performance that cache the logging state MAY return stale values. +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 users needs to call this API each time they generate From 0edaa930d4b9ec43112a0ad2ae43defa19ab7578 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Thu, 23 May 2024 08:49:55 -0700 Subject: [PATCH 11/11] Update specification/logs/bridge-api.md --- specification/logs/bridge-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 552b704b540..001bd00d345 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -148,7 +148,7 @@ This API MUST return a language idiomatic boolean type. A returned value of 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 users needs to call this API each time they generate +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