From d64d795e07d8cafadc847fedbc9428e5dc5450b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 9 Sep 2024 10:11:38 +0200 Subject: [PATCH 1/8] Define Enabled parameters for Logger --- CHANGELOG.md | 2 ++ specification/logs/bridge-api.md | 19 ++++++++++++++++--- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2cec8b69643..8c182f8066b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,8 @@ release. ([#4067](https://github.com/open-telemetry/opentelemetry-specification/pull/4067)) - Clarify that `Export` MUST NOT be called by simple and batching processors concurrently. ([#4173](https://github.com/open-telemetry/opentelemetry-specification/pull/4173)) +- Define `Enabled` parameters for `Logger`. + ([#4203](https://github.com/open-telemetry/opentelemetry-specification/pull/4203)) ### Events diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 6fccedd6f87..3a23c50f02a 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -139,9 +139,22 @@ All parameters are optional. 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. +The API SHOULD accept the following parameters: + +- The [Context](../context/README.md) associated with the `LogRecord`. The API + MAY implicitly use the current Context as a default behavior. +- [Severity Number](./data-model.md#field-severitynumber) + +All parameters MUST be optional. + +Parameters can be added in the future, therefore, +the API MUST be structured in a way for parameters to be added. + +It SHOULD be possible to distinguish between an unset parameter value from +a parameter value set explicitly to a valid default value of given type +(e.g. distinguish unset attributes for empty attributes). The exception from +this rule is when the default value of given is not seen as a valid value like +0 for [Severity Number](./data-model.md#field-severitynumber). This API MUST return a language idiomatic boolean type. A returned value of `true` means the `Logger` is enabled for the provided arguments, and a returned From ddcc1f9a230c3ce37f0b989fee9ac2ea88a6a3b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 9 Sep 2024 10:53:12 +0200 Subject: [PATCH 2/8] Update bridge-api.md --- specification/logs/bridge-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 3a23c50f02a..4bb20cacee3 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -153,8 +153,8 @@ the API MUST be structured in a way for parameters to be added. It SHOULD be possible to distinguish between an unset parameter value from a parameter value set explicitly to a valid default value of given type (e.g. distinguish unset attributes for empty attributes). The exception from -this rule is when the default value of given is not seen as a valid value like -0 for [Severity Number](./data-model.md#field-severitynumber). +this rule is when the default value of given type is not seen as a valid value +like 0 for [Severity Number](./data-model.md#field-severitynumber). This API MUST return a language idiomatic boolean type. A returned value of `true` means the `Logger` is enabled for the provided arguments, and a returned From ee684602679c5dc1362e5d6bbe80d34e35bd9a42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 9 Sep 2024 21:19:11 +0200 Subject: [PATCH 3/8] Improve Context parameter description --- specification/logs/bridge-api.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 4bb20cacee3..6f548fecc6b 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -122,9 +122,8 @@ The API MUST accept the following parameters: - [Timestamp](./data-model.md#field-timestamp) - [Observed Timestamp](./data-model.md#field-observedtimestamp). If unspecified the implementation SHOULD set it equal to the current time. -- The [Context](../context/README.md) associated with the `LogRecord`. The API - MAY implicitly use the current Context as a default - behavior. +- The [Context](../context/README.md) associated with the `LogRecord`. + When implicit Context is supported, the current Context SHOULD be used by default. - [Severity Number](./data-model.md#field-severitynumber) - [Severity Text](./data-model.md#field-severitytext) - [Body](./data-model.md#field-body) @@ -141,8 +140,8 @@ generating a `LogRecord`, a `Logger` SHOULD provide this `Enabled` API. The API SHOULD accept the following parameters: -- The [Context](../context/README.md) associated with the `LogRecord`. The API - MAY implicitly use the current Context as a default behavior. +- The [Context](../context/README.md) to be associated with the `LogRecord`. + When implicit Context is supported, the current Context SHOULD be used by default. - [Severity Number](./data-model.md#field-severitynumber) All parameters MUST be optional. From b916c0f4df62dfd5c89ca8e702a9feac5a1f3918 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 9 Sep 2024 21:44:53 +0200 Subject: [PATCH 4/8] Context SHOULD be required when only explicit context is supported --- specification/logs/bridge-api.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 6f548fecc6b..7a0629fba13 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -119,17 +119,17 @@ The effect of calling this API is to emit a `LogRecord` to the processing pipeli The API MUST accept the following parameters: -- [Timestamp](./data-model.md#field-timestamp) -- [Observed Timestamp](./data-model.md#field-observedtimestamp). If unspecified the +- [Timestamp](./data-model.md#field-timestamp) (optional) +- [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified the implementation SHOULD set it equal to the current time. - The [Context](../context/README.md) associated with the `LogRecord`. - When implicit Context is supported, the current Context SHOULD be used by default. -- [Severity Number](./data-model.md#field-severitynumber) -- [Severity Text](./data-model.md#field-severitytext) -- [Body](./data-model.md#field-body) -- [Attributes](./data-model.md#field-attributes) - -All parameters are optional. + When implicit Context is supported, then this parameter SHOULD be optional and + if unspecified then MUST use current Context. + When only explicit Context is supported, this parameter SHOULD be required. +- [Severity Number](./data-model.md#field-severitynumber) (optional) +- [Severity Text](./data-model.md#field-severitytext) (optional) +- [Body](./data-model.md#field-body) (optional) +- [Attributes](./data-model.md#field-attributes) (optional) #### Enabled @@ -141,10 +141,10 @@ generating a `LogRecord`, a `Logger` SHOULD provide this `Enabled` API. The API SHOULD accept the following parameters: - The [Context](../context/README.md) to be associated with the `LogRecord`. - When implicit Context is supported, the current Context SHOULD be used by default. -- [Severity Number](./data-model.md#field-severitynumber) - -All parameters MUST be optional. + When implicit Context is supported, then this parameter SHOULD be optional and + if unspecified then MUST use current Context. + When only explicit Context is supported, this parameter SHOULD be required. +- [Severity Number](./data-model.md#field-severitynumber) (optional) Parameters can be added in the future, therefore, the API MUST be structured in a way for parameters to be added. From 970557de4f194ac91704110ffe680ace3cc1a7d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 9 Sep 2024 21:46:53 +0200 Subject: [PATCH 5/8] Refine future compatibility --- specification/logs/bridge-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 7a0629fba13..067174c7bba 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -146,8 +146,8 @@ The API SHOULD accept the following parameters: When only explicit Context is supported, this parameter SHOULD be required. - [Severity Number](./data-model.md#field-severitynumber) (optional) -Parameters can be added in the future, therefore, -the API MUST be structured in a way for parameters to be added. +Optional parameters can be added in the future, therefore, +the API MUST be structured in a way for optional parameters to be added. It SHOULD be possible to distinguish between an unset parameter value from a parameter value set explicitly to a valid default value of given type From 0be758290d47616173e5c9872c09e4880af03c31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 9 Sep 2024 21:51:17 +0200 Subject: [PATCH 6/8] Use 'unspecified' term for consistency --- specification/logs/bridge-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 067174c7bba..6a96e4427e3 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -149,11 +149,11 @@ The API SHOULD accept the following parameters: Optional parameters can be added in the future, therefore, the API MUST be structured in a way for optional parameters to be added. -It SHOULD be possible to distinguish between an unset parameter value from +It SHOULD be possible to distinguish between an unspecified parameter value from a parameter value set explicitly to a valid default value of given type -(e.g. distinguish unset attributes for empty attributes). The exception from -this rule is when the default value of given type is not seen as a valid value -like 0 for [Severity Number](./data-model.md#field-severitynumber). +(e.g. distinguish unspecified attributes for empty attributes). The exception +from this rule is when the default value of given type is not seen as a valid +value like 0 for [Severity Number](./data-model.md#field-severitynumber). This API MUST return a language idiomatic boolean type. A returned value of `true` means the `Logger` is enabled for the provided arguments, and a returned From ea03089b486aebd7ccc65ddda6cbb09d09f66827 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 10 Sep 2024 18:27:29 +0200 Subject: [PATCH 7/8] Update specification/logs/bridge-api.md --- specification/logs/bridge-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 6a96e4427e3..2b092ddfa13 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -146,8 +146,8 @@ The API SHOULD accept the following parameters: When only explicit Context is supported, this parameter SHOULD be required. - [Severity Number](./data-model.md#field-severitynumber) (optional) -Optional parameters can be added in the future, therefore, -the API MUST be structured in a way for optional parameters to be added. +Additional optional parameters can be added in the future, therefore, +the API MUST be structured in a way for these parameters to be added. It SHOULD be possible to distinguish between an unspecified parameter value from a parameter value set explicitly to a valid default value of given type From 5df127790e906ca1a3b979947b7a8c11bf48b72c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 10 Sep 2024 18:27:50 +0200 Subject: [PATCH 8/8] Update specification/logs/bridge-api.md Co-authored-by: Tyler Yahn --- 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 2b092ddfa13..fd310fc09b7 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -143,7 +143,7 @@ The API SHOULD accept the following parameters: - The [Context](../context/README.md) to be associated with the `LogRecord`. When implicit Context is supported, then this parameter SHOULD be optional and if unspecified then MUST use current Context. - When only explicit Context is supported, this parameter SHOULD be required. + When only explicit Context is supported, accepting this parameter is REQUIRED. - [Severity Number](./data-model.md#field-severitynumber) (optional) Additional optional parameters can be added in the future, therefore,