Define semantic conventions and instrumentation stability (#2180)

This PR defines the rules for SDKs in all languages with regards to marking
instrumentations as "Stable" and "Unstable" and how such instrumentations
are allowed to evolve over time.

Summary of changes:

- Explain that schemas define what changes are allowed.
- Clarify that additive changes are an exception and are always allowed.
- Prohibit instrumentation changes until April 1, 2023 to allow recipients
  (backends/vendors) to start understanding Schema URLs/Schema Files.
  This gives one year advance notice, which I think should be enough for
  all parties to prepare.

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