Guidance for required experimental db attributes / metrics

[JamieDanielson]

In otel-js we are updating semantic conventions and adding in the option for semconv stability opt-in for database. The migration guide specifies that if someone uses database for their opt-in value you should "emit the stable database conventions, and stop emitting the experimental database conventions that the instrumentation emitted previously." This makes sense when there is a clear stable replacement for a previous value. I see the note in the guide that this "is only intended to be used when migrating from an experimental semantic convention to its initial stable version". For example, the old experimental db.system will stop being emitted in favor of the new stable db.system.name.

I am trying to understand the appropriate attributes/metrics to emit for experimental attributes/metrics that have changed over time. For example, we are currently emitting db.client.connections.usage, and the latest (still experimental) name is db.client.connection.count. This is my understanding of what attributes/metrics we should emit:

• default: db.client.connections.usage
• database, database/dup: db.client.connections.usage

In other words, because this experimental attribute/metrics has no stable replacement, it is treated separately from the stable attributes/metrics and should be emitted regardless of opt-in selection because it is already being emitted. If we at some point add in a flag for database_latest_experimental or another opt-in experimental flag, then we may emit db.client.connection.count... and if that value changes again (as proposed in 2982) it's okay because it's behind the experimental flag.

I am wanting to confirm if I have the correct understanding or if I am missing some nuance or other guidance.

cc @open-telemetry/javascript-maintainers

[joaopgrassi]

My interpretation aligns with yours, but I think something like what you suggested may make things more clear (e.g., database_latest_experimental. Because if one uses OTEL_SEMCONV_STABILITY_OPT_IN=database, one may assume/expect that only stable things are included and no other experimental/in developement convention to be emitted.

we probably should improve this.

[joaopgrassi]

CC @open-telemetry/semconv-db-approvers

[JamieDanielson]

My interpretation aligns with yours, but I think something like what you suggested may make things more clear (e.g., database_latest_experimental. Because if one uses OTEL_SEMCONV_STABILITY_OPT_IN=database, one may assume/expect that only stable things are included and no other experimental/in developement convention to be emitted.

we probably should improve this.

Also we will have a similar situation as with messaging_latest_experimental:

It hasn't occurred yet, but when some messaging conventions do stabilize, we will be in a situation where someone wants both stable conventions where available and latest experimental where not yet stable. I'm not sure if this is just being pedantic, but we may want to consider specifying the behavior in that scenario. Would I use messaging_latest_experimental,messaging/dup? Do I assume messaging_latest_experimental includes stable conventions?

[joaopgrassi]

I'd assume that messaging_latest_experimental emits both latest stable AND experimental conventions.