Transition plan for HTTP breaking changes where both old and new attributes can be sent for a while

[trask]

Fixes #3362

Alternative to #3404

Changes

Adds transition plan for upcoming breaking changes to the unstable HTTP semantic conventions.

[tedsuo]

If double publishing is optional, how should users configure it? Should we define an ENV VAR?

[trask]

If double publishing is optional, how should users configure it? Should we define an ENV VAR?

OTEL_PRESTABLE_SEMANTIC_ATTRIBUTES=old|new|both (with default value old)?

[tigrannajaryan]

If double publishing is optional, how should users configure it? Should we define an ENV VAR?

OTEL_PRESTABLE_SEMANTIC_ATTRIBUTES=old|new|both (with default value old)?

Perhaps, alternatively, OTEL_USE_SEMCONV_VER=x.x.x or OTEL_USE_SEMCONV_VER=x.x.x,y.y.y (with list of versions), because what is new today is going to be old tomorrow and we don't want to keep introducing new variables. This should fail to start if the particular version or versions are not supported by the implementation. So, if you want both you list both versions. This requires the user to explicitly know which versions they want, which to me looks like a benefits since it forces them to do their homework and know what they are doing and what the implications of it are (since we have dates and transitions associated with versions).

[trask]

I'm worried about trying to create something general (and opening more new questions).

What if we go in the other direction and make it clear that this environment variable is super-targeted to this one-time transition, e.g. something like:

OTEL_SEMANTIC_ATTRIBUTES_V1_21_PLUS=false|true|only (default value of false)

[reyang]

I'm worried about trying to create something general (and opening more new questions).

What if we go in the other direction and make it clear that this environment variable is super-targeted to this one-time transition ...

+1 👍

[trask]

or maybe OTEL_SEMCONV_V1_21_0_TRANSITION_PLAN = false|latest|both (with default false)

[reyang]

LGTM.

[trask]

TODO: expand this beyond only HTTP since changes to network attributes impacts Messaging, Database, RPC, etc

this is addressed now, ptal

[trask]

@tigrannajaryan @arminru @jmacd @dyladan can you take another look at this? thx!

[dyladan]

Seems OK. I guess my only question left is how do we handle future breaks when, for example, messaging is updated? Will the env var accept multiple values like http,messaging/dup?

[dyladan]

think this is the best version of the transition plan i've seen yet

[trask]

Seems OK. I guess my only question left is how do we handle future breaks when, for example, messaging is updated? Will the env var accept multiple values like http,messaging/dup?

my thought is http/dup,messaging/dup

[dyladan]

I'm concerned that we may have gone too far, and made something overly specific. The "one time transition" should refer to stabilizing all current semantic conventions, not just the HTTP conventions. Otherwise, we will continue to generate env vars with each domain we stabilize, and this will become confusing to users. I left more details in an in-line comment.

I think if we take an all or nothing break approach we will have 2 big problems:

1. no good way to roll out gradually. being able to update a single semconv at a time gives users the ability to slowly roll their changes instead of everything all at once
2. there is no telling how long the process will take to update all current semantic conventions, and that doesn't even take into consideration that new ones may be added in the future.

I think given those drawbacks we basically have to do this piece by piece approach unfortunately.

[trask]

I'm concerned that we may have gone too far, and made something overly specific. The "one time transition" should refer to stabilizing all current semantic conventions, not just the HTTP conventions. Otherwise, we will continue to generate env vars with each domain we stabilize, and this will become confusing to users. I left more details in an in-line comment.

@dyladan I think @tedsuo's concern was regarding the earlier approach which was using the super-specific env var OTEL_SEMCONV_V1_21_0_TRANSITION_PLAN

[tedsuo]

This looks great. Thank you Trask and everyone for the thought put into this; I now feel confident with us moving forward with semconv stability in general.