Add transition plan for upcoming breaking changes to the unstable HTTP semantic conventions #3381
Conversation
trask
force-pushed
the
transition-plan
branch
2 times, most recently
from
c3eef69
to
36c100f
Compare
…P semantic conventions
| > | ||
| > After October 1, 2023, HTTP instrumentation published from | ||
| > [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories) | ||
| > which adopt the latest HTTP semantic conventions SHOULD provide 3-months of overlap where |
There was a problem hiding this comment.
is my understanding correct that the overlap time starts on Oct 1 and completes on Jan 1 2024 for everyone? I.e. if I add new instrumentation on Dec 1, I only need one month of overlap and if I ship it on Feb 1 2024, I don't need to worry about 1.20.0?
There was a problem hiding this comment.
the idea here is to create an overlap period when any instrumentation upgrades from the old to new HTTP semconv, so that when users upgrade to a new version and are surprised by the change, they can opt-out of the new semconv and continue emitting the old semconv for some time
There was a problem hiding this comment.
I pushed some clarifications
There was a problem hiding this comment.
Just clarifying: It seems that the answer is whenever I ship instrumentation (even if it's the first version and even if it's 2030), I should still offer 3 month grace period?
If so, I hope we can remove this warning at some point once 1.20.0 support becomes irrelevant
There was a problem hiding this comment.
Oh ya, I need to clarify some more, the intention is that this only applies to instrumentations that previously supported the old semconv and are now updating to the new semconv.
arminru
added
semconv:HTTP
area:semantic-conventions
| @@ -26,6 +26,20 @@ operations. By adding HTTP attributes to metric events it allows for finely tune | |||
|
|
|||
| <!-- tocstop --> | |||
|
|
|||
| > **Warning** | |||
| > HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than | |||
| > [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) | |||
There was a problem hiding this comment.
This is a bit unclear. What does "later than v1.20.0" mean? How are instrumentation developers supposed to know if a particular convention they look at is "later than v1.20.0" or not? Do we plan to label conventions with version number they were introduced from in this document?
There was a problem hiding this comment.
How are instrumentation developers supposed to know if a particular convention they look at is "later than v1.20.0" or not?
I was thinking by looking at the link I provided here that points to v1.20.0 version of the HTTP semantic conventions page.
I can definitely spell that out clearer in this warning.
There was a problem hiding this comment.
Yes, please make it clearer.
There was a problem hiding this comment.
I'm also a bit confused by the sentence, had to read it multiple times but still not sure so here it goes 😅
HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than 1.20
If my understanding is correct, this means until August 1 2023, instrumentations should NOT emit conventions newer than 1.20? (or conventions that were added/modified after 1.20)?
Not sure why but the "later" word there just messed with my brain.
| > **Warning** | ||
| > HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than | ||
| > [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) | ||
| > until August 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions |
There was a problem hiding this comment.
I would highly prefer to extend this period to 6 months.
|
Closing in favor of #3404 |
Part of #3362
I'd like to get consensus in this PR on the high-level transition plan.
Changes
Adds transition plan for upcoming breaking changes to the unstable HTTP semantic conventions.