From ff66b248d5f746651008fb87ce7d672d12991a96 Mon Sep 17 00:00:00 2001
From: Johannes Tax <johannes@johannes.tax>
Date: Tue, 27 Feb 2024 15:42:24 +0100
Subject: [PATCH] Clarify enum attribute value stability guarantees (#3879)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #3847

## Changes

As discussed in the semantic conventions SIG, this PR aims to clarify
stability guarantees provided around well[-known attribute values (aka
`enums`) defined by semantic conventions:

* Changing an existing `enum` value is a breaking change.
* Adding a new value to an `enum` is not a breaking change.


##
* [x] Related issues #3847
* [ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps)
* [ ] Links to the prototypes (when adding or changing features)
* [x]
[`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md)
file updated for non-trivial changes
* [ ]
[`spec-compliance-matrix.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md)
updated if necessary

---------

Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>
---
 CHANGELOG.md                              |  3 +++
 specification/versioning-and-stability.md | 16 ++++++++++++----
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b040c61a9d3..120f8ebf246 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,9 @@ release.
 
 ### Common
 
+- Tighten stability requirements for well-known attribute values.
+  ([#3879](https://github.com/open-telemetry/opentelemetry-specification/pull/3879))
+
 ### Supplementary Guidelines
 
 ## v1.30.0 (2024-02-15)
diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md
index b2632067aad..07a545afb5c 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 in a list of well-known values.
 - [Trace](trace/api.md)
   - The following data on [span](trace/api.md#span):
     - The span name
@@ -190,9 +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 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 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)):
@@ -207,8 +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 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 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)
@@ -217,10 +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
-  - 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 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.