Clarify that OTEL_SEMCONV_STABILITY_OPT_IN is a comma-separated list of values (#104)

Co-authored-by: Reiley Yang <reyang@microsoft.com>

CHANGELOG.md

@@ -78,3 +78,5 @@ release.
   ([#69](https://github.com/open-telemetry/semantic-conventions/pull/69))
 - Clarify when HTTP client spans should end.
   ([#70](https://github.com/open-telemetry/semantic-conventions/pull/70))
+- Clarify that OTEL_SEMCONV_STABILITY_OPT_IN is a comma-separated list of values
+  ([#104](https://github.com/open-telemetry/semantic-conventions/pull/104))

specification/metrics/semantic_conventions/http-metrics.md

@@ -36,15 +36,16 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 >   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:
+>   in the existing major version which is a comma-separated list of values.
->   * `none` - continue emitting whatever version of the old experimental
+>   The only values defined so far are:
->     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.
+>   * 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
+>     the instrumentation was emitting previously.
 > * 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

specification/metrics/semantic_conventions/rpc-metrics.md

@@ -38,15 +38,16 @@ metrics can be filtered for finer grain analysis.
 >   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:
+>   in the existing major version which is a comma-separated list of values.
->   * `none` - continue emitting whatever version of the old experimental
+>   The only values defined so far are:
->     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.
+>   * The default behavior (in the absence of one of these values) is to continue
+>     emitting whatever version of the old experimental networking attributes
+>     the instrumentation was emitting previously.
 > * 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

specification/trace/semantic_conventions/database.md

@@ -31,15 +31,16 @@
 >   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:
+>   in the existing major version which is a comma-separated list of values.
->   * `none` - continue emitting whatever version of the old experimental
+>   The only values defined so far are:
->     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.
+>   * The default behavior (in the absence of one of these values) is to continue
+>     emitting whatever version of the old experimental networking attributes
+>     the instrumentation was emitting previously.
 > * 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

specification/trace/semantic_conventions/http.md

@@ -38,15 +38,16 @@ and various HTTP versions like 1.1, 2 and SPDY.
 >   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:
+>   in the existing major version which is a comma-separated list of values.
->   * `none` - continue emitting whatever version of the old experimental
+>   The only values defined so far are:
->     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.
+>   * 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
+>     the instrumentation was emitting previously.
 > * 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

specification/trace/semantic_conventions/messaging.md

@@ -47,15 +47,16 @@
 >   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:
+>   in the existing major version which is a comma-separated list of values.
->   * `none` - continue emitting whatever version of the old experimental
+>   The only values defined so far are:
->     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.
+>   * The default behavior (in the absence of one of these values) is to continue
+>     emitting whatever version of the old experimental networking attributes
+>     the instrumentation was emitting previously.
 > * 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

specification/trace/semantic_conventions/rpc.md

@@ -40,15 +40,16 @@ This document defines how to describe remote procedure calls
 >   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:
+>   in the existing major version which is a comma-separated list of values.
->   * `none` - continue emitting whatever version of the old experimental
+>   The only values defined so far are:
->     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.
+>   * The default behavior (in the absence of one of these values) is to continue
+>     emitting whatever version of the old experimental networking attributes
+>     the instrumentation was emitting previously.
 > * 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