Transition plan for HTTP breaking changes where both old and new attr…

…ibutes can be sent for a while (#3443)

CHANGELOG.md

@@ -53,6 +53,9 @@ release.
   ([#3390](https://github.com/open-telemetry/opentelemetry-specification/pull/3390))
 - BREAKING: Remove `messaging.consumer.id`, make `messaging.client_id` generic
   ([#3336](https://github.com/open-telemetry/opentelemetry-specification/pull/3336))
+- Add transition plan for upcoming breaking changes to the unstable HTTP semantic
+  conventions.
+  ([#3443](https://github.com/open-telemetry/opentelemetry-specification/pull/3443))
 
 ### Compatibility
 

specification/metrics/semantic_conventions/http-metrics.md

@@ -26,6 +26,30 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing HTTP instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the HTTP or networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in HTTP instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which supports the following values:
+>   * `none` - continue emitting whatever version of the old experimental
+>     HTTP and networking attributes the instrumentation was emitting previously.
+>     This is the default value.
+>   * `http` - emit the new, stable HTTP and networking attributes,
+>     and stop emitting the old experimental HTTP and networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable HTTP and networking attributes,
+>     allowing for a seamless transition.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## HTTP Server
 
 ### Metric: `http.server.duration`

specification/metrics/semantic_conventions/rpc-metrics.md

@@ -28,6 +28,30 @@ metrics can be filtered for finer grain analysis.
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing RPC instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in RPC instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which supports the following values:
+>   * `none` - continue emitting whatever version of the old experimental
+>     networking attributes the instrumentation was emitting previously.
+>     This is the default value.
+>   * `http` - emit the new, stable networking attributes,
+>     and stop emitting the old experimental networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable networking attributes,
+>     allowing for a seamless transition.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## Metric instruments
 
 The following metric instruments MUST be used to describe RPC operations. They

specification/trace/semantic_conventions/database.md

@@ -21,6 +21,30 @@
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing Database instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/database.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in Database instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which supports the following values:
+>   * `none` - continue emitting whatever version of the old experimental
+>     database attributes the instrumentation was emitting previously.
+>     This is the default value.
+>   * `http` - emit the new, stable networking attributes,
+>     and stop emitting the old experimental networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable networking attributes,
+>     allowing for a seamless transition.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 **Span kind:** MUST always be `CLIENT`.
 
 The **span name** SHOULD be set to a low cardinality value representing the statement executed on the database.

specification/trace/semantic_conventions/http.md

@@ -27,6 +27,30 @@ and various HTTP versions like 1.1, 2 and SPDY.
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing HTTP instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the HTTP or networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in HTTP instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which supports the following values:
+>   * `none` - continue emitting whatever version of the old experimental
+>     HTTP and networking attributes the instrumentation was emitting previously.
+>     This is the default value.
+>   * `http` - emit the new, stable HTTP and networking attributes,
+>     and stop emitting the old experimental HTTP and networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable HTTP and networking attributes,
+>     allowing for a seamless transition.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## Name
 
 HTTP spans MUST follow the overall [guidelines for span names](../api.md#span).

specification/trace/semantic_conventions/messaging.md

@@ -37,6 +37,30 @@
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing Messaging instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/messaging.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in Messaging instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which supports the following values:
+>   * `none` - continue emitting whatever version of the old experimental
+>     networking attributes the instrumentation was emitting previously.
+>     This is the default value.
+>   * `http` - emit the new, stable networking attributes,
+>     and stop emitting the old experimental networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable networking attributes,
+>     allowing for a seamless transition.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## Definitions
 
 ### Message

specification/trace/semantic_conventions/rpc.md

@@ -29,6 +29,30 @@ This document defines how to describe remote procedure calls
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing RPC instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in RPC instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which supports the following values:
+>   * `none` - continue emitting whatever version of the old experimental
+>     networking attributes the instrumentation was emitting previously.
+>     This is the default value.
+>   * `http` - emit the new, stable networking attributes,
+>     and stop emitting the old experimental networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable networking attributes,
+>     allowing for a seamless transition.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## Common remote procedure call conventions
 
 A remote procedure calls is described by two separate spans, one on the client-side and one on the server-side.