From 36c80104710678d8f2464333e1274975144fd370 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Tue, 30 Nov 2021 18:35:18 -0500 Subject: [PATCH 1/5] Define semantic conventions and instrumentation stability Summary of changes: - Explain that schemas define what changes are allowed. - Clarify additive changes are an exception and are always allowed. - Prohibit instrumentation changes until July 1, 2022 to allow recipients (backends/vendors) to start understanding Schema URLs/Schema Files. --- CHANGELOG.md | 5 +- specification/telemetry-stability.md | 98 +++++++++++++++++++++++ specification/versioning-and-stability.md | 65 +++++++++++---- 3 files changed, 151 insertions(+), 17 deletions(-) create mode 100644 specification/telemetry-stability.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a9b68363b1..3499b3f7b3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,9 @@ release. ### Common +- Define semantic conventions and instrumentation stability. + ([#2180](https://github.com/open-telemetry/opentelemetry-specification/pull/2180)) + ## v1.10.0 (2022-04-01) ### Context @@ -156,7 +159,7 @@ release. - Add "Mapping Arbitrary Data to OTLP AnyValue" document. ([#2385](https://github.com/open-telemetry/opentelemetry-specification/pull/2385)) -## v1.9.0 (2022-02-10) +## v1.9.0 (2021-02-10) ### Context diff --git a/specification/telemetry-stability.md b/specification/telemetry-stability.md new file mode 100644 index 00000000000..7f3184e02b8 --- /dev/null +++ b/specification/telemetry-stability.md @@ -0,0 +1,98 @@ +# Telemetry Stability + ++**Status**: [Experimental](document-status.md) + +
+Table of Contents + + + +- [Unstable Instrumentations](#unstable-instrumentations) +- [Stable Instrumentations](#stable-instrumentations) + * [Fixed Schema Telemetry Producers](#fixed-schema-telemetry-producers) + * [Schema-File Driven Telemetry Producers](#schema-file-driven-telemetry-producers) + + + +
+ +This section defines stability requirements for telemetry produced by +OpenTelemetry instrumentations. + +All OpenTelemetry-authored instrumentations are labeled to be either `Unstable` or `Stable` +from the perspective of the telemetry they produce. + +Adding of new metrics, spans, span events or log records and adding of +new attributes to spans, span events, log records or resources are considered +additive, non-breaking changes and are always allowed for `Unstable` and `Stable` +instrumentations. + +Other changes in the produced telemetry are regulated by the following rules. + +## Unstable Instrumentations + +Unstable telemetry-producing instrumentations (unstable instrumentations for short) SHOULD +be clearly labeled so by any means the instrumentations authors consider idiomatic for +their language, e.g. via version numbers, artifact names, documentation, etc. + +Unstable instrumentations provide no guarantees about the shape of +the telemetry they produce and how that shape changes over time, from version to version. +Span or metric names, attributes of any telemetry items may change without any +restrictions. The produced telemetry MAY specify a Schema URL if the telemetry data +conforms to a particular Schema. + +Unstable instrumentations authored by OpenTelemetry MAY produce telemetry that is +not described by OpenTelemetry semantic conventions. + +TODO: decide if it is necessary to indicate on the wire if the produced telemetry is +coming from an unstable instrumentation. + +## Stable Instrumentations + +Stable telemetry-producing instrumentations (stable instrumentations for short) SHOULD +be clearly labeled so by any means the instrumentations authors consider idiomatic for +their language, e.g. via version numbers, artifact names, documentation, etc. + +Stable instrumentations fall into 2 categories: fixed-schema producers and schema-file +driven producers. + +Stable instrumentations authored by OpenTelemetry SHOULD NOT produce telemetry that is +not described by OpenTelemetry semantic conventions. If, however, this rule is broken the +instrumentations MUST NOT change such telemetry, regardless of whether they +are fixed-schema producers or schema-file driven producers. Once the produced telemetry +is added to the semantic conventions, changes will be allowed as described below. + +### Fixed Schema Telemetry Producers + +Instrumentations that are labeled `Stable` and do not include the Schema URL in the +produced telemetry are called Fixed Schema Telemetry Producers. + +Such instrumentations are prohibited from changing any produced telemetry. If the +specification changes over time and the semantic conventions are updated, the +instrumentation is still prohibited from adopting the changes. If the instrumentation +wishes to adopt the semantic convention changes it must first become a +[Schema-File Driven Telemetry Producer](#schema-file-driven-telemetry-producers) by +adding an appropriate Schema URL in the produced telemetry. + +### Schema-File Driven Telemetry Producers + +Stable instrumentations that include the Schema URL in the produced telemetry are +called Schema-File Driven Telemetry Producers. + +Such instrumentations are prohibited from changing the produced telemetry until +April 1, 2023 and until that date are subject to exactly the same restrictions as +[Fixed Schema Telemetry Producers](#fixed-schema-telemetry-producers). + +After April 1, 2023, stable instrumentations are allowed to change the produced telemetry +if all the following conditions are fulfilled: + +- The change is part of OpenTelemetry semantic conventions and is in a released + version of the specification, +- The change has a corresponding + [published](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#opentelemetry-schema) + OpenTelemetry Schema File that describes the change. +- The produced telemetry correctly specifies the Schema URL. + +If the change was introduced in the semantic conventions specification before +April 1, 2023, the instrumentations must wait until April 1, 2023 before they can adopt +the change and begin producing the changed telemetry. diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 8a4125598eb..e7b242a9de7 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -15,8 +15,8 @@ - [Extending Existing API Calls](#extending-existing-api-calls) + [SDK Stability](#sdk-stability) + [Contrib Stability](#contrib-stability) - + [NOT DEFINED: Telemetry Stability](#not-defined-telemetry-stability) - + [NOT DEFINED: Semantic Conventions Stability](#not-defined-semantic-conventions-stability) + + [Semantic Conventions Stability](#semantic-conventions-stability) + + [Telemetry Stability](#telemetry-stability) * [Deprecated](#deprecated) * [Removed](#removed) * [A note on replacing signals](#a-note-on-replacing-signals) @@ -134,11 +134,14 @@ Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary. #### Contrib Stability -**NOTE: Until telemetry stability is defined, Contrib instrumentation MUST NOT be marked as stable. See below.** - -Plugins, instrumentation, and other contrib packages SHOULD be kept up to date and compatible with the latest versions of the API, SDK, and Semantic Conventions. -If a release of the API, SDK, or Semantic Conventions contains changes which are relevant to a contrib package, that package SHOULD be updated and released in a timely fashion. -The goal is to ensure users can update to the latest version of OpenTelemetry, and not be held back by the plugins that they depend on. +Plugins, instrumentation, and other contrib packages SHOULD be kept up to date +and compatible with the latest versions of the API, SDK, and Semantic +Conventions. If a release of the API, SDK, or Semantic Conventions contains +changes which are relevant to a contrib package, that package SHOULD be updated +and released in a timely fashion. (See limitations on instrumentation stability +in [Telemetry Stability](telemetry-stability.md)). The goal is to ensure users can +update to the latest version of OpenTelemetry, and not be held back by the +plugins that they depend on. Public portions of contrib packages (constructors, configuration, interfaces) SHOULD remain backwards compatible. @@ -149,20 +152,50 @@ For example, a database integration may break stability if the required database However, it is strongly RECOMMENDED that older contrib packages remain stable. A new, incompatible version of an integration SHOULD be released as a separate contrib package, rather than break the existing contrib package. -#### NOT DEFINED: Telemetry Stability +#### Semantic Conventions Stability + +Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid +breaking analysis tools, such as dashboards and alerts. To achieve this, while +allowing the evolution of telemetry and semantic conventions, OpenTelemetry +relies on the concept of +[schemas](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md). + +Changes to semantic conventions in this specification are allowed, provided that +the changes can be described by schema files. The following changes can be +currently described and are allowed: + +- Renaming of attributes. +- Renaming of metrics. +- Renaming of span events. + +All such changes MUST be described in the OpenTelemetry +[Schema File Format](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.0.0.md) +and published +[here](https://github.com/open-telemetry/opentelemetry-specification/tree/main/schemas). +For details see [how OpenTelemetry Schemas are +published](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#opentelemetry-schema). + +See [Telemetry Stability](telemetry-stability.md) document for details on how +instrumentations can use schemas to change the instrumentation they produce. -**Telemetry stability guarantees are TBD.** +In addition to the 3 types of changes described above there are certain types +that are always allowed. Such changes do not need to be described (and are not +described) by schema files. Here is the list of such changes: -Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid breaking analysis tools, such as dashboards and alerts. -However, it is not clear at this time what type of instrumentation changes (for example, adding additional spans and attributes) would actually cause a breaking change. +- Adding new attributes to the existing semantic conventions for resources, + spans, span events or log records. +- Adding semantic conventions for new types of resources, spans, span events, + metrics or log records. -#### NOT DEFINED: Semantic Conventions Stability +Any other changes to semantic conventions are currently prohibited. Other types +of changes MAY be introduced in the future versions of this specification. This +is only allowed if OpenTelemetry introduces a new schema file format that is +capable of describing such changes. -Telemetry stability, including semantic conventions, is not currently defined. The following practices are recommended. +#### Telemetry Stability -Semantic Conventions SHOULD NOT be removed once they are added. -New conventions MAY be added to replace usage of older conventions, but the older conventions SHOULD NOT be removed. -Older conventions SHOULD be marked as deprecated when they are replaced by newer conventions. +For stability of telemetry produced by instrumentation see +[Telemetry Stability](telemetry-stability.md) document. ### Deprecated From acea6420c54a0f4b2d1c0b1301fd15d27a1b641a Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 25 Mar 2022 12:46:56 -0400 Subject: [PATCH 2/5] Fixes based on PR comments --- specification/telemetry-stability.md | 8 ++++---- specification/versioning-and-stability.md | 13 +++++++------ 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/specification/telemetry-stability.md b/specification/telemetry-stability.md index 7f3184e02b8..70b376fb90a 100644 --- a/specification/telemetry-stability.md +++ b/specification/telemetry-stability.md @@ -41,8 +41,8 @@ Span or metric names, attributes of any telemetry items may change without any restrictions. The produced telemetry MAY specify a Schema URL if the telemetry data conforms to a particular Schema. -Unstable instrumentations authored by OpenTelemetry MAY produce telemetry that is -not described by OpenTelemetry semantic conventions. +Unstable instrumentations authored by OpenTelemetry MAY produce additional telemetry that +is not described by OpenTelemetry semantic conventions. TODO: decide if it is necessary to indicate on the wire if the produced telemetry is coming from an unstable instrumentation. @@ -87,11 +87,11 @@ After April 1, 2023, stable instrumentations are allowed to change the produced if all the following conditions are fulfilled: - The change is part of OpenTelemetry semantic conventions and is in a released - version of the specification, + version of the specification. - The change has a corresponding [published](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#opentelemetry-schema) OpenTelemetry Schema File that describes the change. -- The produced telemetry correctly specifies the Schema URL. +- The produced telemetry correctly specifies the respective Schema URL. If the change was introduced in the semantic conventions specification before April 1, 2023, the instrumentations must wait until April 1, 2023 before they can adopt diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index e7b242a9de7..d282dcbd77e 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -139,7 +139,7 @@ and compatible with the latest versions of the API, SDK, and Semantic Conventions. If a release of the API, SDK, or Semantic Conventions contains changes which are relevant to a contrib package, that package SHOULD be updated and released in a timely fashion. (See limitations on instrumentation stability -in [Telemetry Stability](telemetry-stability.md)). The goal is to ensure users can +in [Telemetry Stability](telemetry-stability.md).) The goal is to ensure users can update to the latest version of OpenTelemetry, and not be held back by the plugins that they depend on. @@ -158,13 +158,13 @@ Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid breaking analysis tools, such as dashboards and alerts. To achieve this, while allowing the evolution of telemetry and semantic conventions, OpenTelemetry relies on the concept of -[schemas](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md). +[Telemetry Schemas](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md). Changes to semantic conventions in this specification are allowed, provided that the changes can be described by schema files. The following changes can be currently described and are allowed: -- Renaming of attributes. +- Renaming of span, metric, log and resource attributes. - Renaming of metrics. - Renaming of span events. @@ -175,7 +175,7 @@ and published For details see [how OpenTelemetry Schemas are published](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#opentelemetry-schema). -See [Telemetry Stability](telemetry-stability.md) document for details on how +See the [Telemetry Stability](telemetry-stability.md) document for details on how instrumentations can use schemas to change the instrumentation they produce. In addition to the 3 types of changes described above there are certain types @@ -183,7 +183,8 @@ that are always allowed. Such changes do not need to be described (and are not described) by schema files. Here is the list of such changes: - Adding new attributes to the existing semantic conventions for resources, - spans, span events or log records. + spans, span events or log records. Note that adding attributes to existing metrics is + considered to be a breaking change. - Adding semantic conventions for new types of resources, spans, span events, metrics or log records. @@ -194,7 +195,7 @@ capable of describing such changes. #### Telemetry Stability -For stability of telemetry produced by instrumentation see +For stability of telemetry produced by instrumentation see the [Telemetry Stability](telemetry-stability.md) document. ### Deprecated From 8622ec2dca0bf4da7ba4072043479788ad7e1336 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 28 Mar 2022 11:00:21 -0400 Subject: [PATCH 3/5] Change absolute links to relative --- specification/telemetry-stability.md | 3 +-- specification/versioning-and-stability.md | 9 +++------ 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/specification/telemetry-stability.md b/specification/telemetry-stability.md index 70b376fb90a..02f6f555bc2 100644 --- a/specification/telemetry-stability.md +++ b/specification/telemetry-stability.md @@ -88,8 +88,7 @@ if all the following conditions are fulfilled: - The change is part of OpenTelemetry semantic conventions and is in a released version of the specification. -- The change has a corresponding - [published](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#opentelemetry-schema) +- The change has a corresponding [published](schemas/overview.md#opentelemetry-schema) OpenTelemetry Schema File that describes the change. - The produced telemetry correctly specifies the respective Schema URL. diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index d282dcbd77e..9d12822bd19 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -158,7 +158,7 @@ Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid breaking analysis tools, such as dashboards and alerts. To achieve this, while allowing the evolution of telemetry and semantic conventions, OpenTelemetry relies on the concept of -[Telemetry Schemas](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md). +[Telemetry Schemas](schemas/overview.md). Changes to semantic conventions in this specification are allowed, provided that the changes can be described by schema files. The following changes can be @@ -169,11 +169,8 @@ currently described and are allowed: - Renaming of span events. All such changes MUST be described in the OpenTelemetry -[Schema File Format](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.0.0.md) -and published -[here](https://github.com/open-telemetry/opentelemetry-specification/tree/main/schemas). -For details see [how OpenTelemetry Schemas are -published](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#opentelemetry-schema). +[Schema File Format](schemas/file_format_v1.0.0.md) and published [here](../schemas). +For details see [how OpenTelemetry Schemas are published](schemas/overview.md#opentelemetry-schema). See the [Telemetry Stability](telemetry-stability.md) document for details on how instrumentations can use schemas to change the instrumentation they produce. From 89ead2d7b0c4854e8268000e63328a61f8f65d6a Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 28 Mar 2022 11:03:34 -0400 Subject: [PATCH 4/5] Change absolute links to relative --- 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 9d12822bd19..b42bec11e0a 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -169,7 +169,7 @@ currently described and are allowed: - Renaming of span events. All such changes MUST be described in the OpenTelemetry -[Schema File Format](schemas/file_format_v1.0.0.md) and published [here](../schemas). +[Schema File Format](schemas/file_format_v1.0.0.md) and published in this repository. For details see [how OpenTelemetry Schemas are published](schemas/overview.md#opentelemetry-schema). See the [Telemetry Stability](telemetry-stability.md) document for details on how From 8f664e7ba3dedada9ceeb3e458c542ef5e6ffee8 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 8 Apr 2022 13:49:32 -0400 Subject: [PATCH 5/5] Fix changelog date --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3499b3f7b3c..70efdaaed94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -159,7 +159,7 @@ release. - Add "Mapping Arbitrary Data to OTLP AnyValue" document. ([#2385](https://github.com/open-telemetry/opentelemetry-specification/pull/2385)) -## v1.9.0 (2021-02-10) +## v1.9.0 (2022-02-10) ### Context