diff --git a/.chloggen/992.yaml b/.chloggen/992.yaml new file mode 100644 index 0000000000..52b89da098 --- /dev/null +++ b/.chloggen/992.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Finalizes the migration requirement for instrumentations to follow when updating to stable database semconv. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 719 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index e40ef7bb6a..d56e5b3e1c 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -31,11 +31,30 @@ and attributes but more may be added in the future. > **Warning** +> > Existing database instrumentations that are using -> [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md) -> (or prior) SHOULD NOT change the version of the database conventions that they emit -> until a transition plan to the (future) stable semantic conventions has been published. -> Conventions include, but are not limited to, attributes, metric and span names, and unit of measure. +> [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 +> 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 introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` +> in the existing major version which is a comma-separated list of values. +> If 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. +> * 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 +> for at least six months after it starts emitting both sets of conventions. +> * SHOULD drop the environment variable in the next major version. ## Database operation diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 6425213bff..dd170bedc2 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -18,34 +18,27 @@ linkTitle: Client Calls > **Warning** +> > Existing database instrumentations that are using > [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 -> until a transition plan to the (future) stable semantic conventions has been published. -> Conventions include, but are not limited to, attributes, metric and span names, and unit of measure. -> -> **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 conventions that they emit -> until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking conventions which are also used -> in Database instrumentations). Conventions include, but are not limited to, attributes, +> * SHOULD NOT change the version of the database conventions that they emit +> 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 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 conventions, -> and stop emitting the old experimental networking conventions +> If 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. -> * `http/dup` - emit both the old and the stable networking conventions, +> * `database/dup` - emit both the old and the stable database 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 conventions +> emitting whatever version of the old experimental database conventions > the instrumentation was emitting previously. -> * Note: `http/dup` has higher precedence than `http` in case both values are present +> * 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 > for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version.