From f2368dcdc3ef56b31d817134454cc7a5615b6a10 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Thu, 15 Feb 2024 11:36:34 +0100 Subject: [PATCH 1/7] Clarify enum attribute value stability guarantees --- specification/versioning-and-stability.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index b2632067aad..c7388ab9260 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -183,6 +183,7 @@ Semantic Conventions defines the set of fields in the OTLP data model: - Attribute keys - provided to [get a tracer](trace/api.md#get-a-tracer) - provided to [get a meter](metrics/api.md#get-a-meter) + - Attribute values that are defined as `enums` - [Trace](trace/api.md) - The following data on [span](trace/api.md#span): - The span name @@ -190,9 +191,11 @@ Semantic Conventions defines the set of fields in the OTLP data model: - The attribute keys provided to the span - Whether these attributes must be provided at span start time, due to sampling concerns. + - The attribute values provided to the span that are defined as `enums`. - The following data provided on [span events](trace/api.md#add-events) - The event name - The attribute keys provided for the event + - The attribute values provided for the event that are defined as `enums` - [Metrics](metrics/api.md) - The following portions of a Metric (passed when constructing [an instrument](metrics/api.md#instrument)): @@ -207,8 +210,10 @@ Semantic Conventions defines the set of fields in the OTLP data model: both synchronous and asynchronous instruments. - These exist on `NumberDataPoint`, `HistogramDataPoint`, `ExponentialHistogramDataPoint` and `SummaryDataPoint`. + - The attribute values on any `*DataPoint` that are defined as `enums`. - [Log Records](logs/data-model.md#log-and-event-record-definition) - The attribute keys provided on the LogRecord + - The attribute values provided on the LogRecord that are defined as `enums` - For log records that are [Log Events](logs/event-api.md) - The following data provided to [emit event](logs/event-api.md#emit-event): - The event name (the value of the `event.name` attribute) @@ -217,10 +222,8 @@ Things not listed in the above are not expected to remain stable via semantic convention and are allowed (or expected) to change. A few examples: - The values of attributes - - Specifically for `enums` the list of allowed values is expected to change - overtime. - - Even for `enums` that limit allowed values to semconv, some may need to - updated values in the future. Tooling should expect unknown values. + - An exception are existing values for `enums`, However, new values for + `enums` can be added. Tooling should expect unknown values. - The links attached to a span - The recorded measurement type (float or integer) of a metric is not enforced and allowed to change. - The description of a metric instrument. From 166de78bb96ae6873a4be9027a945acb33533db2 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Thu, 15 Feb 2024 11:39:25 +0100 Subject: [PATCH 2/7] Fix punctuation --- specification/versioning-and-stability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index c7388ab9260..175a13afbd3 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -222,7 +222,7 @@ Things not listed in the above are not expected to remain stable via semantic convention and are allowed (or expected) to change. A few examples: - The values of attributes - - An exception are existing values for `enums`, However, new values for + - An exception are existing values for `enums`. However, new values for `enums` can be added. Tooling should expect unknown values. - The links attached to a span - The recorded measurement type (float or integer) of a metric is not enforced and allowed to change. From 4e853404572a8092a2657f1ba362cf4441bd1f52 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Thu, 15 Feb 2024 11:43:49 +0100 Subject: [PATCH 3/7] Add changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 76527c73380..6385bd2b956 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -42,6 +42,9 @@ release. ### Common +- Clarify stability requirements for enum attribute values + ([#3879](https://github.com/open-telemetry/opentelemetry-specification/pull/3879)) + ### Supplementary Guidelines ## v1.29.0 (2024-01-10) From 34f72ab57a396652cf9b990085d89fc7be9f4272 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 16 Feb 2024 09:18:31 +0100 Subject: [PATCH 4/7] Update CHANGELOG.md Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6385bd2b956..9ba5b8a58e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -42,7 +42,7 @@ release. ### Common -- Clarify stability requirements for enum attribute values +- Tighten stability requirements for enum attribute values ([#3879](https://github.com/open-telemetry/opentelemetry-specification/pull/3879)) ### Supplementary Guidelines From fa0c96e7d4e628d6d3c42c59e5a8fa266581b718 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 16 Feb 2024 09:18:46 +0100 Subject: [PATCH 5/7] Update specification/versioning-and-stability.md Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- specification/versioning-and-stability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 175a13afbd3..75102551d25 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -223,7 +223,7 @@ convention and are allowed (or expected) to change. A few examples: - The values of attributes - An exception are existing values for `enums`. However, new values for - `enums` can be added. Tooling should expect unknown values. + `enums` can be added. Consumers should expect unknown values. - The links attached to a span - The recorded measurement type (float or integer) of a metric is not enforced and allowed to change. - The description of a metric instrument. From afda501f5667a05ca6536ba7aa938d0915c99950 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 16 Feb 2024 16:26:28 +0100 Subject: [PATCH 6/7] PR comments --- specification/versioning-and-stability.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 75102551d25..07a545afb5c 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -183,7 +183,7 @@ Semantic Conventions defines the set of fields in the OTLP data model: - Attribute keys - provided to [get a tracer](trace/api.md#get-a-tracer) - provided to [get a meter](metrics/api.md#get-a-meter) - - Attribute values that are defined as `enums` + - Attribute values that are defined in a list of well-known values. - [Trace](trace/api.md) - The following data on [span](trace/api.md#span): - The span name @@ -191,11 +191,13 @@ Semantic Conventions defines the set of fields in the OTLP data model: - The attribute keys provided to the span - Whether these attributes must be provided at span start time, due to sampling concerns. - - The attribute values provided to the span that are defined as `enums`. + - The attribute values provided to the span that are defined in a list of + well-known values. - The following data provided on [span events](trace/api.md#add-events) - The event name - The attribute keys provided for the event - - The attribute values provided for the event that are defined as `enums` + - The attribute values provided for the event that are defined in a list of + well-known values. - [Metrics](metrics/api.md) - The following portions of a Metric (passed when constructing [an instrument](metrics/api.md#instrument)): @@ -210,10 +212,12 @@ Semantic Conventions defines the set of fields in the OTLP data model: both synchronous and asynchronous instruments. - These exist on `NumberDataPoint`, `HistogramDataPoint`, `ExponentialHistogramDataPoint` and `SummaryDataPoint`. - - The attribute values on any `*DataPoint` that are defined as `enums`. + - The attribute values on any `*DataPoint` that are defined in a list of + well-known values. - [Log Records](logs/data-model.md#log-and-event-record-definition) - The attribute keys provided on the LogRecord - - The attribute values provided on the LogRecord that are defined as `enums` + - The attribute values provided on the LogRecord that are defined in a list + of well-known values. - For log records that are [Log Events](logs/event-api.md) - The following data provided to [emit event](logs/event-api.md#emit-event): - The event name (the value of the `event.name` attribute) @@ -222,8 +226,9 @@ Things not listed in the above are not expected to remain stable via semantic convention and are allowed (or expected) to change. A few examples: - The values of attributes - - An exception are existing values for `enums`. However, new values for - `enums` can be added. Consumers should expect unknown values. + - An exception are existing values in lists of well-known values. However, + new values can be added to such lists. Consumers should expect unknown + values. - The links attached to a span - The recorded measurement type (float or integer) of a metric is not enforced and allowed to change. - The description of a metric instrument. From 0aa4628a7ff1910af1bc9a6f1e4dc7cbffb472a3 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 23 Feb 2024 11:11:55 +0100 Subject: [PATCH 7/7] Update CHANGELOG.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f3a66364f9d..4350e130d2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,7 +25,7 @@ release. ### Common -- Tighten stability requirements for enum attribute values +- Tighten stability requirements for well-known attribute values. ([#3879](https://github.com/open-telemetry/opentelemetry-specification/pull/3879)) ### Supplementary Guidelines