otelmongo: support OTEL_SEMCONV_STABILITY_OPT_IN for v1.26.0 semconv

[prestonvasquez]

Resolves #6171, #2165

The specifications for maintaining multiple semantic convention versions is documented here: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md.

To use a non-default version:

export OTEL_SEMCONV_STABILITY_OPT_IN=database

To include both v1.26.0 and v1.21.0:

export OTEL_SEMCONV_STABILITY_OPT_IN=database/dup

To include the default (v1.21.0) version:

unset OTEL_SEMCONV_STABILITY_OPT_IN

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 76.1%. Comparing base (b991afd) to head (aa7f16f).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##            main   #6172     +/-   ##
=======================================
+ Coverage   76.0%   76.1%   +0.1%     
=======================================
  Files        219     220      +1     
  Lines      21387   21448     +61     
=======================================
+ Hits       16265   16335     +70     
+ Misses      4561    4555      -6     
+ Partials     561     558      -3     

Files with missing lines	Coverage Δ
.../mongo/otelmongo/internal/semconv/event_monitor.go	100.0% <100.0%> (ø)
....mongodb.org/mongo-driver/mongo/otelmongo/mongo.go	90.0% <100.0%> (+4.2%)	⬆️

... and 1 file with indirect coverage changes

[prestonvasquez]

@pellared @dmathieu following up on issue #5551

[dmathieu]

Updating semconv is definitely not just a chore, especially since, as you mention, there are field name changes (which can cause issues with users, since they need to change their queries and dashboards).

We should either mark these breaking changes explicitely in a changelog entry, or follow a similar migration path as the otelhttp instrumentation is doing: #5132

[pellared]

We should either mark these breaking changes explicitely in a changelog entry, or follow a similar migration path as the otelhttp instrumentation is doing: #5132

@open-telemetry/specs-semconv-maintainers, @open-telemetry/semconv-db-approvers, do you have some recommendations or feedback regarding changes of database semantic conventions? Are we supposed to do some migrations in instrumentation libraries like for HTTP instrumentations?

CC @XSAM as you are the maintainer of https://github.com/XSAM/otelsql which AFAIK is the most popular instrumentation library for database/sql.

[trask]

check out https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md:

Warning

Existing database instrumentations that are using v1.24.0 of this document (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.

[pellared]

I would rather first have a PR which bumps semconv to v1.24.0

[prestonvasquez]

I would rather first have a PR which bumps semconv to v1.24.0

@pellared Could you clarify this?

[trask]

I would rather first have a PR which bumps semconv to v1.24.0

would this go against the semconv recommendation?

SHOULD NOT change the version of the database conventions that they emit by default until the database semantic conventions are marked stable.

[prestonvasquez]

@pellared

Please remember to also update the PR description.

Could you clarify this?

[pellared]

@pellared

Please remember to also update the PR description.

Could you clarify this?

It does not reflect current changes of the PR

[pellared]

@prestonvasquez, I meant the PR description (not title) 😉

[prestonvasquez]

@prestonvasquez, I meant the PR description (not title) 😉

Whoops I was doing this on my phone, guess I didn't hit save.

[pellared]

@prestonvasquez, thank you for your work 👍