From 3f8cd169961981e64c10b78622476431f86d6bde Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 8 May 2023 12:00:16 -0700 Subject: [PATCH] Transition plan for HTTP breaking changes where both old and new attributes can be sent for a while (#3443) --- .../semantic_conventions/http-metrics.md | 24 +++++++++++++++++++ .../semantic_conventions/rpc-metrics.md | 24 +++++++++++++++++++ .../trace/semantic_conventions/database.md | 24 +++++++++++++++++++ .../trace/semantic_conventions/http.md | 24 +++++++++++++++++++ .../trace/semantic_conventions/messaging.md | 24 +++++++++++++++++++ .../trace/semantic_conventions/rpc.md | 24 +++++++++++++++++++ 6 files changed, 144 insertions(+) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 968b05754..5d0703c0c 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 6508a2af2..69992fd24 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 36bff3d54..26813fd82 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 dba45b01b..b4be87588 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 4c57ed823..0b83502a2 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 b70a97fa7..ededc08ff 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.