Proposal for version-specific database semantic conventions using OTEL_SEMCONV_STABILITY_OPT_IN

[prestonvasquez]

Area(s)

area:telemetry

Is your change request related to a problem? Please describe.

The Semantic Conventions for Database Client Calls introduced in open-telemetry/opentelemetry-specification#3404 and open-telemetry/opentelemetry-specification#3443 does not account for more than one breaking semantic convention update per major version. At most, OTEL_SEMCONV_STABILITY_OPT_IN can support a single upgrade (database), the original conventions (unset), and both the original and the upgrae (database/dup). Suggest updating the documentation to support a more extensible pattern that takes a comma separated list of semantic convention versions supported by the telemetry library. For example:

To use a non-default version:

export OTEL_SEMCONV_STABILITY_OPT_IN=mongo/v1.26.0

To include multiple versions:

export OTEL_SEMCONV_STABILITY_OPT_IN=mongo/v1.26.0,mongo/v1.24.0

To include all versions:

export OTEL_SEMCONV_STABILITY_OPT_IN=mongo/dup

To include only the default version:

unset OTEL_SEMCONV_STABILITY_OPT_IN

Describe the solution you'd like

Update the documentation concerning OTEL_SEMCONV_STABILITY_OPT_IN to include the following language:

The environment variable SHOULD also support specific versions such as database/v1.26.0,database/v1.24.0. The versioning within the list allows for more granular control over which database semantic convention are emitted.

Describe alternatives you've considered

There are only two solutions to this: either support exactly one/many semantic convention update(s) per major version. If this issue is rejected, we should include the rationale in the documentation.

Additional context

This was brought up in open-telemetry/opentelemetry-go-contrib#6172 to update the semantic conventions for otelmongo.

[trask]

when a stable instrumentation introduces breaking changes to its telemetry, the instrumentation will need to take a major version bump (from a semantic versioning perspective), see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#semantic-conventions-stability)

once we release a first stable database semconv, then instrumentations will be able to release a stable version

after that, if we introduce a breaking change to the stable database semconv (which would require a very high bar before we do this), then those stable instrumentations will need to take a major version bump to adopt the breaking change

if this doesn't answer your question, could you give a concrete example picking a specific instrumentation and playing out its release cycle over time and which releases it would take in a breaking database semconv change? thanks!

[prestonvasquez]

This makes sense, should we link to the Semantic Conventions Stability guarantee in the upgrade documentation? Something like this:

Upgrading semconv that would cause a breaking change has the expectation of a major version bump, which is why this solution only accounts for the existing semconv dependency and the newest one. See here for rational.

[trask]

so, a second part I realized is that I think we only considered using OTEL_SEMCONV_STABILITY_OPT_IN for the initial unstable to stable migration, and not subsequent major version bumps from stable -> (breaking) stable

otherwise we may have named it differently like OTEL_SEMCONV_MAJOR_VERSION_OPT_IN (or something better..)

and maybe we will still need something like that, I do think we're pretty narrowly focused on initial stability for now, and hoping we don't have to deal with a stable -> stable major version bump for at least a few years

that said, I'm definitely supportive of adding some kind of clarification to the migration guide