Skip to content

Commit

Permalink
Prohibit usage of retired names in semantic conventions (#2191)
Browse files Browse the repository at this point in the history
* Prohibit usage of retired names in semantic conventions

This change adds a prohibition clause that requires that no old
metric or attribute name is used for a new attribute.

This is important to ensure reversibility of schema transformation
(converting from a new version to an old version of schema).

Without this restriction the following is possible:

Schema version 1. Attribute A exists.
Schema version 2. Attribute A is renamed to B. Appropriate schema file is created.
Schema version 3. Attribute A is introduced (a completely different new attribute).

Now attempting to go from Version 3 to version 1 is impossible since it requires
renaming B to A (for the change in version 2), but a different attribute A already exists.

* Fix based on comments

* Add changelog entry

Co-authored-by: Carlos Alberto Cortez <calberto.cortez@gmail.com>
  • Loading branch information
2 people authored and jsuereth committed Nov 16, 2023
1 parent 537b07f commit 14280a4
Showing 1 changed file with 10 additions and 0 deletions.
10 changes: 10 additions & 0 deletions specification/common/attribute-naming.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
<!-- toc -->

- [Name Pluralization guidelines](#name-pluralization-guidelines)
- [Name Reuse Prohibition](#name-reuse-prohibition)
- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors)
- [Recommendations for Application Developers](#recommendations-for-application-developers)
- [otel.* Namespace](#otel-namespace)
Expand Down Expand Up @@ -67,6 +68,15 @@ Names SHOULD follow these rules:
[Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization)
SHOULD be followed for the attribute name.

## Name Reuse Prohibition

A new attribute MUST NOT be added with the same name as an attribute that
existed in the past but was renamed (with a corresponding schema file).

When introducing a new attribute name check all existing schema files to make
sure the name does not appear as a key of any "rename_attributes" section (keys
denote old attribute names in rename operations).

## Recommendations for OpenTelemetry Authors

- All names that are part of OpenTelemetry semantic conventions SHOULD be part
Expand Down

0 comments on commit 14280a4

Please sign in to comment.