diff --git a/CHANGELOG.md b/CHANGELOG.md index c16c4ef0e41..a88f974ab70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,9 @@ release. ### Telemetry Schemas +- Define semantic conventions and instrumentation stability. + ([#2180](https://github.com/open-telemetry/opentelemetry-specification/pull/2180)) + ## v1.8.0 (2021-11-12) ### Context diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 8a4125598eb..b08a6891b27 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -7,28 +7,28 @@ -- [Design goals](#design-goals) -- [Signal lifecycle](#signal-lifecycle) +* [Design goals](#design-goals) +* [Signal lifecycle](#signal-lifecycle) * [Experimental](#experimental) * [Stable](#stable) - + [API Stability](#api-stability) - - [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) + * [API Stability](#api-stability) + * [Extending Existing API Calls](#extending-existing-api-calls) + * [SDK Stability](#sdk-stability) + * [Contrib Stability](#contrib-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) -- [Version numbers](#version-numbers) +* [Version numbers](#version-numbers) * [Major version bump](#major-version-bump) * [Minor version bump](#minor-version-bump) * [Patch version bump](#patch-version-bump) -- [Long Term Support](#long-term-support) +* [Long Term Support](#long-term-support) * [API support](#api-support) * [SDK Support](#sdk-support) * [Contrib Support](#contrib-support) -- [OpenTelemetry GA](#opentelemetry-ga) +* [OpenTelemetry GA](#opentelemetry-ga) @@ -149,20 +149,70 @@ 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 - -**Telemetry stability guarantees are TBD.** - -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. - -#### NOT DEFINED: Semantic Conventions Stability - -Telemetry stability, including semantic conventions, is not currently defined. The following practices are recommended. - -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. +#### 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). + +In addition to the 3 types of changes described above, adding conventions for +new attributes, resources, metrics, spans, span events or log records is always +allowed. Such changes do not need to be described (and are not described) by +schema files. + +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 + +This section defines stability requirements for telemetry produced by +instrumentations, such as OpenTelemetry SDKs. + +Instrumentations, which include the Schema URL in the produced telemetry are +allowed to change the produced telemetry after July 1, 2022 if both of the +following conditions are fulfilled: + +- The change is part of OpenTelemetry semantic conventions and are 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. + +If the change was introduced in the specification before July 1, 2022 the +instrumentations must wait until July 1, 2022 before they can adopt the change +and begin producing the changed telemetry. + +Instrumentations, which do not include the Schema URL in the produced telemetry +are prohibited from changing any produced telemetry that is described by +OpenTelemetry semantic conventions. + +Note that adding of new attributes, metrics, spans, span events or log records +are considered additive, non-breaking changes and are always allowed, whether +the instrumentation includes the Schema URL in the produced telemetry or no. + +OpenTelemetry SDKs SHOULD NOT produce telemetry that is not described by +OpenTelemetry semantic conventions. If, however, this rule is broken the SDKs +MUST NOT change such telemetry, regardless of whether they include the Schema +URL in the produced telemetry or no. ### Deprecated