Provide clear guidance on what semconv actually enforces (#3225)

Fixes #2864
Fixes #2883

## Changes

- Explicitly define what is "enforced" by stability guarantees from
Semantic conventions.
- We enforce attribute key names + types, across resource, span, metric
and log
  - We enforce span names
  - We enforce metric names, units
- Expand allowed changes to semconv to include metric attributes that do
not increase timeseries count for a given metric.

## Context

Sig discussion thread/doc
[here](https://docs.google.com/document/d/1Nvcf1wio7nDUVcrXxVUN_f8MNmcs0OzVAZLvlth1lYY/edit?usp=sharing).

---------

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
Co-authored-by: Johannes Tax <johannes@johannes.tax>
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>
Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>
Co-authored-by: Carlos Alberto Cortez <calberto.cortez@gmail.com>
Co-authored-by: Tyler Benson <tylerbenson@gmail.com>
Co-authored-by: Joshua Carpeggiani <32605850+joshcarp@users.noreply.github.com>
Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com>
Co-authored-by: Asaf Mesika <asaf.mesika@gmail.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com>
Co-authored-by: Antoine Toulme <antoine@lunar-ocean.com>
Co-authored-by: Christian Neumüller <christian+github@neumueller.me>
Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
Co-authored-by: Reiley Yang <reyang@microsoft.com>
Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com>

CHANGELOG.md

@@ -54,6 +54,8 @@ release.
   [#3348](https://github.com/open-telemetry/opentelemetry-specification/pull/3348))
 - Define attributes collected for `cosmosdb` by Cosmos DB SDK
   ([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
+- Clarify stability requirements of semantic conventions
+  ([#3225](https://github.com/open-telemetry/opentelemetry-specification/pull/3225))
 
 ### Compatibility
 

specification/versioning-and-stability.md

@@ -155,12 +155,78 @@ A new, incompatible version of an integration SHOULD be released as a separate c
 
 #### Semantic Conventions Stability
 
+Semantic conventions define a contract between the signals that instrumentation
+will provide and analysis tools that consumes the instrumentation (e.g.
+dashboards, alerts, queries, etc.).
+
 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/README.md).
 
+Semantic Conventions defines breaking changes as those that would break the
+common usage of tooling written against the telemetry it produces. That is, the
+portions of telemetry where specialized tooling (alerts, dashboards, e.g.)
+interact are expected to remain stable for that tooling *after schema
+transformations are applied*. These also assume no user interventions in the
+default configuration, e.g. Samplers, Views, etc.
+
+Semantic Conventions defines the set of fields in the OTLP data model:
+
+- [Resource](resource/sdk.md)
+  - attribute keys. (The key section of attributes key value pairs)
+- InstrumentationScope
+  - Attribute keys
+    - provided to [get a tracer](trace/api.md#get-a-tracer)
+    - provided to [get a meter](metrics/api.md#get-a-meter)
+- [Trace](trace/api.md)
+  - The following data on [span](trace/api.md#span):
+    - The span name
+    - The span kind
+    - The attribute keys provided to the span
+      - Whether these attributes must be provided at span start time, due to
+        sampling concerns.
+  - The following data provided on [span events](trace/api.md#add-events)
+    - The event name
+    - The attribute keys provided for the event
+- [Metrics](metrics/api.md)
+  - The following portions of a Metric
+    (passed when constructing [an instrument](metrics/api.md#instrument)):
+    - The name of the metric (defaults to instrument name).
+    - The kind of metric data (Gauge, Sum, Histogram, ExponentialHistogram)
+      - For `Counter` and `UpDownCounter` instruments, it is
+        acceptable to change between asynchronous and synchronous instruments,
+        as this preserves the metric kind.
+    - The unit of the metric (defaults to instrument unit).
+  - The attribute keys on any `*DataPoint`.
+    - These are provided in the API when recording a measurement, for
+      both synchronous and asynchronous instruments.
+    - These exist on `NumberDataPoint`, `HistogramDataPoint`,
+      `ExponentialHistogramDataPoint` and `SummaryDataPoint`.
+- [Log Records](logs/bridge-api.md#logrecord)
+  - The attribute keys provided on the LogRecord
+  - For log records that are [Log Events](logs/event-api.md)
+    - The following data provided to [emit event](logs/event-api.md#emit-event):
+      - The event name (the value of the `event.name` attribute)
+      - The event domain (the value of the `event.domain` attribute)
+
+Things not listed in the above are not expected to remain stable via semantic
+convention and are allowed (or expected) to change. A few examples:
+
+- The values of attributes
+  - Specifically for `enums` the list of allowed values is expected to change
+    overtime.
+  - Even for `enums` that limit allowed values to semconv, some may need to
+    updated values in the future. Tooling should expect unknown values.
+- The links attached to a span
+- The recorded measurement type (float or integer) of a metric is not enforced and allowed to change.
+- The description of a metric instrument.
+- The values being recorded by an instrument.
+
+The list of telemetry fields which are covered by stability guarantees MAY be
+extended.
+
 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:
@@ -181,8 +247,9 @@ 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. Note that adding attributes to existing metrics is
-  considered to be a breaking change.
+  spans, span events or log records.
+- Adding new attributes to existing metrics that do not "break apart" existing
+  timeseries, such that alert thresholds would break / need to change.
 - Adding semantic conventions for new types of resources, spans, span events,
   metrics or log records.