From 5298ea906487737fc2cc16fb43fc0fd3824d8135 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 3 Oct 2024 08:45:17 -0700 Subject: [PATCH] Copy database semconv warning from spans/metrics to general README (#1445) Co-authored-by: Liudmila Molkova --- docs/database/README.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/database/README.md b/docs/database/README.md index 7fcb8d42a8..fcc769028a 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -13,11 +13,30 @@ This document defines semantic conventions for database client spans as well as database metrics and logs. > **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/README.md) -> (or prior) SHOULD NOT change the version of the database conventions that they emit by default -> 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 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 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. Semantic conventions for database operations are defined for the following signals: