From 6cbdc54ff3343ebccf557ef2e352f850ba114c74 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 11 Apr 2023 11:33:07 -0700 Subject: [PATCH] Add moratorium on relying on schema transformations for telemetry stability --- CHANGELOG.md | 3 +++ specification/telemetry-stability.md | 12 ++++++------ specification/versioning-and-stability.md | 3 +++ 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4921c3137ad..d983048db5c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,9 @@ release. ### Semantic Conventions +- Add moratorium on relying on schema transformations for telemetry stability + ([#3380](https://github.com/open-telemetry/opentelemetry-specification/pull/3380)) + ### Compatibility ### OpenTelemetry Protocol diff --git a/specification/telemetry-stability.md b/specification/telemetry-stability.md index 96cd0690381..882f1f93f35 100644 --- a/specification/telemetry-stability.md +++ b/specification/telemetry-stability.md @@ -49,6 +49,9 @@ coming from an unstable instrumentation. ## Stable Instrumentations +> **Warning** +> There is a moratorium on relying on schema transformations for telemetry stability. + 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. @@ -80,10 +83,11 @@ Stable instrumentations that include the Schema URL in the produced telemetry ar 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 +the moratorium on relying on schema transformations for telemetry stability is lifted +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 +After the moratorium is lifted, 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 @@ -91,7 +95,3 @@ if all the following conditions are fulfilled: - The change has a corresponding [published](schemas/README.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 f56162543e5..a771d52587f 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -155,6 +155,9 @@ A new, incompatible version of an integration SHOULD be released as a separate c #### Semantic Conventions Stability +> **Warning** +> There is a moratorium on relying on schema transformations for telemetry 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.).