Skip to content

Commit

Permalink
Clarify enum attribute value stability guarantees (#3879)
Browse files Browse the repository at this point in the history
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 <[email protected]>
Co-authored-by: Robert Pająk <[email protected]>
  • Loading branch information
3 people authored Feb 27, 2024
1 parent 116d189 commit ff66b24
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 4 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
16 changes: 12 additions & 4 deletions specification/versioning-and-stability.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,16 +183,21 @@ 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
- The span kind
- 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)):
Expand All @@ -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)
Expand All @@ -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.
Expand Down

0 comments on commit ff66b24

Please sign in to comment.