diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a9b68363b1..70efdaaed94 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 diff --git a/specification/telemetry-stability.md b/specification/telemetry-stability.md new file mode 100644 index 00000000000..02f6f555bc2 --- /dev/null +++ b/specification/telemetry-stability.md @@ -0,0 +1,97 @@ +# 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 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. + +## 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](schemas/overview.md#opentelemetry-schema) + OpenTelemetry Schema File that describes the change. +- 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 +the change and begin producing the changed telemetry. diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 8a4125598eb..b42bec11e0a 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,48 @@ 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 +[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 +currently described and are allowed: + +- Renaming of span, metric, log and resource attributes. +- Renaming of metrics. +- 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 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 +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. 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. -#### 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 the +[Telemetry Stability](telemetry-stability.md) document. ### Deprecated