Define semantic conventions and instrumentation stability

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

specification/telemetry-stability.md

@@ -0,0 +1,97 @@
+# Telemetry Stability
+
++**Status**: [Experimental](document-status.md)
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [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)
+
+<!-- tocstop -->
+
+</details>
+
+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.

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