From ccf2ba7d98e32b4156be9aafa6e13b9b11f84bf1 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 3 Dec 2021 09:30:25 -0500 Subject: [PATCH 1/3] 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. --- specification/common/attribute-naming.md | 11 +++++++++++ specification/metrics/semantic_conventions/README.md | 11 +++++++++++ specification/trace/semantic_conventions/README.md | 10 ++++++++++ 3 files changed, 32 insertions(+) diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 1cf593b9f73..80469fe82f9 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -8,6 +8,7 @@ - [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) @@ -67,6 +68,16 @@ 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 + +It is prohibited to introduce a new attribute with a name that matches a name of +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 diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index d69feee26f5..757e7db3675 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -7,6 +7,7 @@ - [General Guidelines](#general-guidelines) + * [Name Reuse Prohibition](#name-reuse-prohibition) * [Units](#units) * [Pluralization](#pluralization) - [General Metric Semantic Conventions](#general-metric-semantic-conventions) @@ -66,6 +67,16 @@ and confusion for end users. (For example, prefer `process.runtime.java.gc*` ove `process.runtime.gc.*`.) Measures of many operating system metrics are similarly ambiguous. +### Name Reuse Prohibition + +It is prohibited to introduce a new metric with a name that matches a name of +a metric that existed in the past but was renamed (with a corresponding +schema file). + +When introducing a new metric name check all existing schema files to make sure +the name does not appear as a key of any "rename_metrics" section (keys denote +old metric names in rename operations). + ### Units Conventional metrics or metrics that have their units included in diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md index dae734a96aa..bfc9fe2f72b 100644 --- a/specification/trace/semantic_conventions/README.md +++ b/specification/trace/semantic_conventions/README.md @@ -31,3 +31,13 @@ The following library-specific semantic conventions are defined: Apart from semantic conventions for traces and [metrics](../../metrics/semantic_conventions/README.md), OpenTelemetry also defines the concept of overarching [Resources](../../resource/sdk.md) with their own [Resource Semantic Conventions](../../resource/semantic_conventions/README.md). + +## Event Name Reuse Prohibition + +It is prohibited to introduce a new event with a name that matches a name of an +event that existed in the past but was renamed (with a corresponding schema +file). + +When introducing a new event name check all existing schema files to make sure +the name does not appear as a key of any "rename_events" section (keys denote +old event names in rename operations). From 19b33db27566c0fea764e0ee522a8a4b538071ac Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 10 Dec 2021 14:25:24 -0500 Subject: [PATCH 2/3] Fix based on comments --- specification/common/attribute-naming.md | 5 ++--- specification/metrics/semantic_conventions/README.md | 5 ++--- specification/trace/semantic_conventions/README.md | 5 ++--- 3 files changed, 6 insertions(+), 9 deletions(-) diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 80469fe82f9..9cd2f187b5a 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -70,9 +70,8 @@ Names SHOULD follow these rules: ## Name Reuse Prohibition -It is prohibited to introduce a new attribute with a name that matches a name of -an attribute that existed in the past but was renamed (with a corresponding -schema file). +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 diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index 757e7db3675..d2d43adf060 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -69,9 +69,8 @@ ambiguous. ### Name Reuse Prohibition -It is prohibited to introduce a new metric with a name that matches a name of -a metric that existed in the past but was renamed (with a corresponding -schema file). +A new metric MUST NOT be added with the same name as a metric that existed in +the past but was renamed (with a corresponding schema file). When introducing a new metric name check all existing schema files to make sure the name does not appear as a key of any "rename_metrics" section (keys denote diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md index bfc9fe2f72b..f1e37be01db 100644 --- a/specification/trace/semantic_conventions/README.md +++ b/specification/trace/semantic_conventions/README.md @@ -34,9 +34,8 @@ OpenTelemetry also defines the concept of overarching [Resources](../../resource ## Event Name Reuse Prohibition -It is prohibited to introduce a new event with a name that matches a name of an -event that existed in the past but was renamed (with a corresponding schema -file). +A new event MUST NOT be added with the same name as an event that existed in +the past but was renamed (with a corresponding schema file). When introducing a new event name check all existing schema files to make sure the name does not appear as a key of any "rename_events" section (keys denote From 66b37fa710b93f422194e0c613a9931829836e64 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 13 Dec 2021 09:27:40 -0500 Subject: [PATCH 3/3] Add changelog entry --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c671913f26..a003caf433f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,9 @@ release. ### Semantic Conventions +- Prohibit usage of retired names in semantic conventions. + ([#2191](https://github.com/open-telemetry/opentelemetry-specification/pull/2191)) + ### Compatibility - Simplify Baggage handling in the OpenTracing Shim layer.