Add warning on database semconv about not adopting any new breaking changes until database semconv stability is reached

[trask]

(similar to the HTTP warning that is in place)

[trask]

Sent #733 to remove this as an immediate blocker to database semconv stability work.

I'm hoping not to require a major version bump for database instrumentations that are currently marked alpha (the way we did for HTTP). From the Java Instrumentation perspective, this could require us to bump the Java agent major version again, and also because (at least today) our whole repo shares the same version and we would prefer not to bump all instrumentation major versions again.

[jack-berg]

I'm hoping not to require a major version bump for database instrumentations that are currently marked alpha

Requiring changes to databases semconv to have a major version bump changes the anecdote that HTTP required it into a trend. I.e. it will be hard to say that any future stabilization effort shouldn't have a major version bump requirement when all the precedent says that's how its done. On the surface, requiring a major version bump seems like an easy safe option. But looking closer reveals that doing so imposes a higher load on maintainers / contributors which has a chilling effect on progress. Also, instrumentations that have frequent major version bumps don't inspire confidence in users. Imagine if the otel java agent needed to publish a 3.x while 2.x is still hot off the press? It gives the impression that we don't treat major versions seriously.

IMO the cost of overall project health incurred by requiring major version bumps for every stabilization effort is worse than the wrath we'll face from re-affirming that when we say something is experimental and comes with no guarantees, we mean it.

[tedsuo]

Is it not reasonable to bump the major version when we make a breaking change? Aren't we lying if we don't? If we don't want a major bump, we should try our best to not make breaking changes but to just be additive.

fwiw, I think that instrumentation libraries only need a major version bump when the breaking convention directly affects the telemetry they produce. This is the version number that end users actually care about. Java is an exception in the sense that it bundles all of these libraries together into a single package. Most languages do not.

[jack-berg]

Is it not reasonable to bump the major version when we make a breaking change? Aren't we lying if we don't?

For stable code, conventions, and specifications, yes. For experimental code, conventions, and specifications, no. There's no point in having an experimental status if we're still obliged to act like its stable anyway.

[tedsuo]

Yes, but we agreed that we have left this instrumentation in a defacto stable state for far too long, and hiding behind a technicality is unacceptable given the damage it would inflict.

Assuming that we are talking about a breaking change, you’d be breaking all of their dashboards and reducing them to flying blind until they build new ones and repopulate them. That’s a pretty big surprise to unleash in a minor version bump. Many users automatically update to new minor versions.

I don’t agree with the notion that only a small handful of end users would be bothered by this change. It is incredibly destructive in a way that is extremely noticeable.

For Java, if you would like to reduce the number of major version bumps, there is a strategy. You could hold off on pulling out the old instrumentation until you have collected a sufficient amount of it. The breaking change is when we remove the old stuff, not when we add the new stuff.

[jack-berg]

Yes, but we agreed that we have left this instrumentation in a defacto stable state for far too long, and hiding behind a technicality is unacceptable given the damage it would inflict.

We decided that database semantic conventions were defacto stable? I thought we decided that for http conventions, but don't remember a discussion about database. (I think this issue is that discussion 🙂) What's your litmus test for when something is defacto stable? Do you envision us requiring a major version bump for the stabilization effort of every convention which includes breaking changes?

[trask]

I'm reluctant to major version bump the Java Instrumentation again this year, as @jack-berg says #719 (comment):

instrumentations that have frequent major version bumps don't inspire confidence in users. Imagine if the otel java agent needed to publish a 3.x while 2.x is still hot off the press? It gives the impression that we don't treat major versions seriously.

If we decide to require major version bumps for stable Database, RPC, and Messaging semconvs, then Java Instrumentation could always implement them as opt-in this year but wait until 2025 to enable them by default and release 3.0.

[tedsuo]

If we decide to require major version bumps for stable Database, RPC, and Messaging semconvs, then Java Instrumentation could always implement them as opt-in this year but wait until 2025 to enable them by default and release 3.0.

I think that would be a very reasonable approach for Java!

Again, I don't believe that other languages (except maybe .NET(?)) would have an issue with major version bumps.

[tedsuo]

We decided that database semantic conventions were defacto stable? I thought we decided that for http conventions, but don't remember a discussion about database. (I think this issue is that discussion 🙂) What's your litmus test for when something is defacto stable? Do you envision us requiring a major version bump for the stabilization effort of every convention which includes breaking changes?

It is all de facto stable 🙂. My litmus test would be "how widely adopted is this telemetry?" crossed with "how critical is this telemetry?". It is fair to say that database clients are widely adopted, and their telemetry is critical.

[cijothomas]

If we decide to require major version bumps for stable Database, RPC, and Messaging semconvs, then Java Instrumentation could always implement them as opt-in this year but wait until 2025 to enable them by default and release 3.0.

I think that would be a very reasonable approach for Java!

Again, I don't believe that other languages (except maybe .NET(?)) would have an issue with major version bumps.

.NET never did major bumps, even for http semantic conventions. (we followed the approach of defaulting to old conventions with an env_variable to switch to new, and then changed the default to new convention, still keeping the env_variable to get back old conventions, and finally, in the first stable release - only new/stable conventions were used, and no ability to go back to old convention.) I don't see a need to do it differently for database conventions. Its also not decided if database instrumentations will offer the env_variable option to smoothen the migration experience - I think it makes sense to do that.