diff --git a/docs/database/README.md b/docs/database/README.md index d3768ebe94..4dd6c14d0e 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -15,25 +15,25 @@ database metrics and logs. > [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) > (or prior): > -> * SHOULD NOT change the version of the database conventions that they emit by default -> until the database semantic conventions are marked stable. -> Conventions include, but are not limited to, attributes, -> metric and span names, and unit of measure. +> * SHOULD NOT change the version of the database conventions that they emit by +> default in their existing major version. 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 as a comma-separated list of category-specific values +> in their existing major version as a comma-separated list of category-specific values > (e.g., http, databases, messaging). The list of values includes: -> * `database` - emit the new, stable database conventions, -> and stop emitting the old experimental database conventions -> that the instrumentation emitted previously. -> * `database/dup` - emit both the old and the stable database conventions, -> allowing for a seamless transition. +> * `database` - emit the stable database conventions, and stop emitting +> the experimental database conventions that the instrumentation emitted +> previously. +> * `database/dup` - emit both the experimental and stable database conventions, +> allowing for a phased rollout of the stable semantic conventions. > * The default behavior (in the absence of one of these values) is to continue > emitting whatever version of the old experimental database conventions > the instrumentation was emitting previously. > * Note: `database/dup` has higher precedence than `database` in case both values are present -> * SHOULD maintain (security patching at a minimum) the existing major version +> * SHOULD maintain (security patching at a minimum) their existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version. +> * MAY drop the environment variable in their next major version and emit only +> the stable database conventions. Semantic conventions for database operations are defined for the following signals: diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 0c4990e670..3a33b0eed8 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -32,25 +32,25 @@ linkTitle: Metrics > [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) > (or prior): > -> * SHOULD NOT change the version of the database conventions that they emit by default -> until the database semantic conventions are marked stable. -> Conventions include, but are not limited to, attributes, -> metric and span names, and unit of measure. +> * SHOULD NOT change the version of the database conventions that they emit by +> default in their existing major version. 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 as a comma-separated list of category-specific values +> in their existing major version as a comma-separated list of category-specific values > (e.g., http, databases, messaging). The list of values includes: -> * `database` - emit the new, stable database conventions, -> and stop emitting the old experimental database conventions -> that the instrumentation emitted previously. -> * `database/dup` - emit both the old and the stable database conventions, -> allowing for a seamless transition. +> * `database` - emit the stable database conventions, and stop emitting +> the experimental database conventions that the instrumentation emitted +> previously. +> * `database/dup` - emit both the experimental and stable database conventions, +> allowing for a phased rollout of the stable semantic conventions. > * The default behavior (in the absence of one of these values) is to continue > emitting whatever version of the old experimental database conventions > the instrumentation was emitting previously. > * Note: `database/dup` has higher precedence than `database` in case both values are present -> * SHOULD maintain (security patching at a minimum) the existing major version +> * SHOULD maintain (security patching at a minimum) their existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version. +> * MAY drop the environment variable in their next major version and emit only +> the stable database conventions. ## Database operation diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index af40f7a9a2..8c2aa7833e 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -23,25 +23,25 @@ linkTitle: Spans > [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) > (or prior): > -> * SHOULD NOT change the version of the database conventions that they emit by default -> until the database semantic conventions are marked stable. -> Conventions include, but are not limited to, attributes, -> metric and span names, and unit of measure. +> * SHOULD NOT change the version of the database conventions that they emit by +> default in their existing major version. 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 as a comma-separated list of category-specific values +> in their existing major version as a comma-separated list of category-specific values > (e.g., http, databases, messaging). The list of values includes: -> * `database` - emit the new, stable database conventions, -> and stop emitting the old experimental database conventions -> that the instrumentation emitted previously. -> * `database/dup` - emit both the old and the stable database conventions, -> allowing for a seamless transition. +> * `database` - emit the stable database conventions, and stop emitting +> the experimental database conventions that the instrumentation emitted +> previously. +> * `database/dup` - emit both the experimental and stable database conventions, +> allowing for a phased rollout of the stable semantic conventions. > * The default behavior (in the absence of one of these values) is to continue > emitting whatever version of the old experimental database conventions > the instrumentation was emitting previously. > * Note: `database/dup` has higher precedence than `database` in case both values are present -> * SHOULD maintain (security patching at a minimum) the existing major version +> * SHOULD maintain (security patching at a minimum) their existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version. +> * MAY drop the environment variable in their next major version and emit only +> the stable database conventions. ## Name diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index 72ecfd961a..eb8d4e1795 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -16,6 +16,9 @@ transitioning to the stable database semantic conventions. Specifically, when existing database instrumentations published by OpenTelemetry are updated to the stable database semantic conventions, they: +- SHOULD NOT change the version of the database conventions that they emit by + default in their existing major version. 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 their existing major version, which accepts: - `database` - emit the stable database conventions, and stop emitting