diff --git a/CHANGELOG.md b/CHANGELOG.md index ac26e0fac4f..0fe750ed25d 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 968b0575494..5d0703c0c5e 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -26,6 +26,30 @@ operations. By adding HTTP attributes to metric events it allows for finely tune +> **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` diff --git a/specification/metrics/semantic_conventions/rpc-metrics.md b/specification/metrics/semantic_conventions/rpc-metrics.md index 6508a2af271..69992fd2420 100644 --- a/specification/metrics/semantic_conventions/rpc-metrics.md +++ b/specification/metrics/semantic_conventions/rpc-metrics.md @@ -28,6 +28,30 @@ metrics can be filtered for finer grain analysis. +> **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 diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 36bff3d5442..26813fd82fb 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -21,6 +21,30 @@ +> **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. diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index dba45b01b57..b4be87588ea 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -27,6 +27,30 @@ and various HTTP versions like 1.1, 2 and SPDY. +> **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). diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 4c57ed823a7..0b83502a27c 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -37,6 +37,30 @@ +> **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 diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index b70a97fa77b..ededc08ff28 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -29,6 +29,30 @@ This document defines how to describe remote procedure calls +> **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.