From 4fcf4dfd795eccec8018f628c1331b3aa1aee99d Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Wed, 30 Aug 2023 04:59:18 -0700 Subject: [PATCH] Clarify stabilization plan does not just apply to attributes (#278) --- docs/database/database-spans.md | 17 +++++++++-------- docs/http/README.md | 17 +++++++++-------- docs/http/http-metrics.md | 17 +++++++++-------- docs/http/http-spans.md | 17 +++++++++-------- docs/messaging/messaging-spans.md | 17 +++++++++-------- docs/rpc/rpc-metrics.md | 17 +++++++++-------- docs/rpc/rpc-spans.md | 17 +++++++++-------- 7 files changed, 63 insertions(+), 56 deletions(-) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 15174ac9f6..d208eebd7a 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -22,24 +22,25 @@ linkTitle: Client Calls > [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 +> * SHOULD NOT change the version of the networking conventions 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). +> include stabilization of a core set of networking conventions which are also used +> in Database instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/http/README.md b/docs/http/README.md index e3bc209b16..a5249266f1 100644 --- a/docs/http/README.md +++ b/docs/http/README.md @@ -18,24 +18,25 @@ and various HTTP versions like 1.1, 2 and SPDY. > [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 +> * SHOULD NOT change the version of the HTTP or networking conventions 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). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 26ad37b78e..e97aebdd8e 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -31,24 +31,25 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > [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 +> * SHOULD NOT change the version of the HTTP or networking conventions 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). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 871dc221b9..7ea7529359 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -37,24 +37,25 @@ and various HTTP versions like 1.1, 2 and SPDY. > [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 +> * SHOULD NOT change the version of the HTTP or networking conventions 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). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index d25a0c57b0..c1814ad8d9 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -38,24 +38,25 @@ > [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 +> * SHOULD NOT change the version of the networking conventions 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). +> include stabilization of a core set of networking conventions which are also used +> in Messaging instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index d80d0c5df4..d431dd6652 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -40,24 +40,25 @@ metrics can be filtered for finer grain analysis. > [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 +> * SHOULD NOT change the version of the networking conventions 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). +> include stabilization of a core set of networking conventions which are also used +> in RPC instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index cf6a054ccc..e5bdaaf29d 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -30,24 +30,25 @@ This document defines how to describe remote procedure calls > [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 +> * SHOULD NOT change the version of the networking conventions 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). +> include stabilization of a core set of networking conventions which are also used +> in RPC instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023).