Guidance for implementation of semantic convention migration plan

[lzchen]

Apologies if this already has been discussed.

Context

The Python SIG has almost all of their instrumentations supporting the old semantic conventions. Only one and a half (one in draft) of the instrumentations have implemented the http semantic conventions migration plan. Recently, we have had contributions/inquiries about our instrumentations that either require an upgrade to the new semantic conventions or is providing a fix/addition to upgrade SOME of an instrumentation to follow new http semantic conventions (e.g. open-telemetry/opentelemetry-python-contrib#2260). We do not want our instrumentations to be in a mixed state, and it is better from a maintenance standpoint to migrate instrumentations entirely and individually. This poses an issue as we are now either forced to block contributors from making contributions to instrumentations that relate to new semantic conventions or introduce a mixture of new semantic conventions with already existing old ones (we don't want to do this).

Issue

The main issue is that the Python SIG, which is already suffering from lack of resources, will not be able to implement the migration plan for all our instrumentations within a reasonable time (specifically allowing configuration for old/new/double pump), however there are users and contributors who are waiting on us to do so. It's possible that this work could take longer than a year, given our lack of contributors. This most likely is an issue in other language SIGs as well. We would like some guidance on how to EASE the burden and implementation work for contributors to be able to ship out new semantic conventions in a reasonable amount of time. For context, it took me (a Python maintainer and also following the http semantic conventions work relatively closely) a couple of days to implement the migration plan for a SINGLE instrumentation (open-telemetry/opentelemetry-python-contrib#2002) and even longer to review and approve from other approvers since most people do not have context about the migration or even semantic convention changes in general (I do admit that there was no migration guide at the time of implementing it and perhaps I am just slow :D).

Possible mitigations

1. Allow a deadline for implementation of the migration plan for instrumentations. If we are passed the deadline and the instrumentation still has not implemented the migration plan, we allow language SIGs to make the decision on whether they want to simply upgrade to new semantic conventions for the next released version of the instrumentation and break users. This is at least possible for Python since all of our instrumentations are experimental. This will at least alleviate SOME implementation burden, and allow contributors that do not have context on the migration plan to assist in simply implementing the new semantic conventions.

2. Allow leniency on WHICH instrumentations must implement the migration plan. We can allow language SIGs to decide which instrumentations they want to implement the migration plan (most likely for the most popular libraries) in a best effort, and allow breakage for every other instrumentation. The instrumentation chosen should be explicitly outlined in whatever migration guidance/documentation language SIGs have.

@trask for visibility

[trask]

Possible mitigations

2. Allow leniency on WHICH instrumentations must implement the migration plan. We can allow language SIGs to decide which instrumentations they want to implement the migration plan (most likely for the most popular libraries) in a best effort, and allow breakage for every other instrumentation. The instrumentation chosen should be explicitly outlined in whatever migration guidance/documentation language SIGs have.

I believe this has been discussed previously, and it makes sense to me.

[joaopgrassi]

Sounds like a topic to bring to the meeting on Monday. I also believe we talked about it, but would be good to get a consensus and reflect this in text somewhere. I will add to the agenda for next week.

@lzchen It would be great if you could join the call as well, at 8 am PT

[lzchen]

From the semconv SIG 3/11/2024:

It seems like mitigation (2) has been met with no objections from the working group. Will bring this up with the TC/specs WIG.
It was outlined that implementors should use data points and/or signals to determine which instrumentations are the most popular to continue implementing the migration plan and not just by "feeling". The most important thing is the user experience and to be transparent with them to have a good path forward.

[jack-berg]

We discussed in the 3/12/2024 spec meeting and there were no dissenting opinions about giving language maintainers agency to not follow the migration plan if they deem that its not necessary / possible (e.g. they lack the resourcing for it to be practical).

@trask noted that the migration plan language uses "SHOULD" instead of must, and that this was intentional to allow for exceptions.

If anyone else has different opinions on this, please speak up.

cc @tedsuo

[tedsuo]

I agree that we need to be pragmatic, and option 2 is realistic.

Also, I should note that it's reasonable to add migration to a specific package in response to end user requests. Given that instrumentation packages must bump a major version number when they implement the new conventions, it will always be possible to come back later and add migration by issuing a new minor version of the previous major version. Perhaps said end users would be willing to do this for us.

[joaopgrassi]

@lzchen this seem to have been addressed and we have a way forward. All good to close this issue?

[lzchen]

Hello Tc members! We are experiencing the same issue now for database semantic conventions. The only difference now is that db semconvs are not yet marked stable (I am not sure what "release candidate" state is). We have a few contributions to important db instrumentations that are trying to implement new sem conv. What is the guidance here? Can we assume "release candidate" is equivalent to stable in that there will be no breaking changes (enough to start migration plan for certain db instrumentations like we did for http)?

[trask]

"release candidate" is the equivalent of the prior "frozen" status

it's not-quite-but-very-close to stable

enough to start migration plan for certain db instrumentations like we did for http

yes!