feat(attributes) bump semconv to 1.26.0

[prestonvasquez]

Resolves #6171, #2165

See issue for migration table.

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=mongo

To include both v1.26.0 and v1.21.0:

export OTEL_SEMCONV_STABILITY_OPT_IN=mongo/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 67.0%. Comparing base (6e79f7c) to head (6de6ad5).

Additional details and impacted files

@@           Coverage Diff           @@
##            main   #6172     +/-   ##
=======================================
+ Coverage   66.9%   67.0%   +0.1%     
=======================================
  Files        193     194      +1     
  Lines      15652   15695     +43     
=======================================
+ Hits       10482   10528     +46     
+ Misses      4880    4878      -2     
+ Partials     290     289      -1     

Files with missing lines	Coverage Δ
....mongodb.org/mongo-driver/mongo/otelmongo/mongo.go	85.8% <100.0%> (+0.1%)	⬆️
...ongodb.org/mongo-driver/mongo/otelmongo/semconv.go	100.0% <100.0%> (ø)

... and 2 files with indirect coverage changes

---- 🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[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.

[trask]

@prestonvasquez OTEL_SEMCONV_STABILITY_OPT_IN is a comma-separated list of values, see

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

• 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

[prestonvasquez]

@prestonvasquez OTEL_SEMCONV_STABILITY_OPT_IN is a comma-separated list of values, see

@trask Would you mind reading the PR description and letting me know if the proposal is in line with the spirit of this requirement?

[pellared]

This pattern does not account for > 2 semantic version update within the lifetime of a major version.

You would need to address it in https://github.com/open-telemetry/semantic-conventions.

This does not prevent bumping semconv to v1.24.0 beforehand.

[trask]

@trask Would you mind reading the PR description and letting me know if the proposal is in line with the spirit of this requirement?

my recommendation would be to stick to what's defined in the semantic conventions

if you're interested, there was a lot of discussion around the OTEL_SEMCONV_STABILITY_OPT_IN mechanism when it was introduced in open-telemetry/opentelemetry-specification#3404 and open-telemetry/opentelemetry-specification#3443 (and refined in some later PRs)

This pattern does not account for > 2 semantic version update within the lifetime of a major version.

You would need to address it in https://github.com/open-telemetry/semantic-conventions.

I'm happy to discuss if you open an issue in https://github.com/open-telemetry/semantic-conventions describing the limitations you are running into with the existing OTEL_SEMCONV_STABILITY_OPT_IN mechanism.

[prestonvasquez]

@pellared

This does not prevent bumping semconv to v1.24.0 beforehand.

What is the purpose of doing this? It seems like this will maintain the existing behavior.

[prestonvasquez]

@trask Would you mind reading the PR description and letting me know if the proposal is in line with the spirit of this requirement?

my recommendation would be to stick to what's defined in the semantic conventions

if you're interested, there was a lot of discussion around the OTEL_SEMCONV_STABILITY_OPT_IN mechanism when it was introduced in open-telemetry/opentelemetry-specification#3404 and open-telemetry/opentelemetry-specification#3443 (and refined in some later PRs)

This pattern does not account for > 2 semantic version update within the lifetime of a major version.

You would need to address it in open-telemetry/semantic-conventions.

I'm happy to discuss if you open an issue in open-telemetry/semantic-conventions describing the limitations you are running into with the existing OTEL_SEMCONV_STABILITY_OPT_IN mechanism.

Issue: open-telemetry/semantic-conventions#1502

[dmathieu]

What is the purpose of doing this? It seems like this will maintain the existing behavior.

Yes, this would be a noop change. It would (a bit virtually) reduce the scope of the upgrade to 1.26 though, as a single version bump would then be required.

[prestonvasquez]

What is the purpose of doing this? It seems like this will maintain the existing behavior.

Yes, this would be a noop change. It would (a bit virtually) reduce the scope of the upgrade to 1.26 though, as a single version bump would then be required.

@dmathieu In this case, should we just close this PR and leave the semconv dependency as-is for now?

[dmathieu]

Sure, if you think there's still too much work for this PR. Maybe document the outcome from the discussion that happened here in #6171?

[prestonvasquez]

@dmathieu I think we should maintain 1.17.0 since upgrading to 1.24.0 has no obvious benefit. However, I'm happy to open a separate PR for 1.24.0 if you want. I would suggest not using the pattern for a non-breaking upgrade, though.

[pellared]

@pellared

This does not prevent bumping semconv to v1.24.0 beforehand.

What is the purpose of doing this? It seems like this will maintain the existing behavior.

Like bumping a dependency - we are closer to the latest version.
Even if nothing changed at least it was double-checked during the bump. Maybe some new attribute has been introduced?

[dmathieu]

Also, folks using the package will have less surprises seeing a newer version in their dependency tree rather than something older that looks like it's not being cared for.

[pellared]

@prestonvasquez, I changed it to draft as it looks like it is still WIP. Please change to ready for review once applicable.

[dmathieu]

Rather than creating one method for each attribute, how about one method which returns all attributes, and can decide their key name.
Kind of like what the otelhttp library does, where we define two structs, one for the old and another for the new version.
https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation/net/http/otelhttp/internal/semconv

I would also move the logic into an internal package, for a better separation of concerns.

[prestonvasquez]

That's an interesting idea. If I understand correctly, you're suggesting we define two separate command monitors specifically for the semantic conventions. Could you explain the benefits of this pattern over the more atomic append* solution proposed in the PR? The goal of the existing solution is to minimize code changes when advancing the library to a desired version, while also avoiding duplication in the monitoring logic.

[dmathieu]

Your solution works if some values are renamed. But if a new value is added, or one is removed then, it becomes trickier to handle since the root method has to know about everything.

With one struct for each semconv version, that struct knows exactly what to do for that version, and that's it. There aren't two versions mixed.
It would also avoid having to define one method for each attribute.

Finally, doing the separation this way also makes it easier to add a third version if we someday need it (I really hope we don't).

[pellared]

At last using the same patterns in multiple modules help in maintenance of the repository.

[prestonvasquez]

@dmathieu Here are my arguments for the factory pattern over struct duplication:

if a new value is added, or one is removed then, it becomes trickier to handle since the root method has to know about everything.

In this case you would just add nil to the unused version, networkHost for example:

func appendNetworkHost(attrs []attribute.KeyValue, h string) []attribute.KeyValue {
	return appendAttrs(attrs, semconv1210.NetPeerName, nil, h)
}

It would also avoid having to define one method for each attribute.

This is pretty low complexity, exchanging 1 line of code for 3 to avoid refactoring the library.

Finally, doing the separation this way also makes it easier to add a third version if we someday need it (I really hope we don't).

By design, there can never be a third version. The clarification of this point can be found here: open-telemetry/semantic-conventions#1502. Additionally, this logic should be rolled back entirely once we release a stable version:

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

[pellared]

@prestonvasquez, please first create a PR which refactors otelhttp. We need to try using similar patterns across the codebase to make it easier to maintain and more readable. Ideally the pattern should be described in https://github.com/open-telemetry/opentelemetry-go/blob/main/CONTRIBUTING.md#style-guide.