[chore][RFC] Semantic conventions migrations in the Collector

[mx-psi]

Description

RFC about dealing with semantic conventions migrations.

This would be applicable to semantic conventions migrations related to RPC, system metrics, Kubernetes metrics and attributes...

RFC Checklist

• Announced on the Jan 14, 2026 Collector SIG meeting
• Mentioned in #otel-collector-dev https://cloud-native.slack.com/archives/C07CCCMRXBK/p1768400424432639

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.82%. Comparing base (97f66a9) to head (96ef779).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #14273      +/-   ##
==========================================
- Coverage   91.83%   91.82%   -0.02%     
==========================================
  Files         677      677              
  Lines       42679    42679              
==========================================
- Hits        39195    39190       -5     
- Misses       2427     2430       +3     
- Partials     1057     1059       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ChrsMark]

Overall looks good, thank's for writing this!

I only have some concerns about specific details.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 14 days.

[mx-psi]

Thanks for your comments @dmathieu @lmolkova @ChrsMark!

I marked this as ready for review because it feels like there is some agreement on the overall shape, but there are still details to figure out. Trying to summarize the main points that we need to discuss:

1. Naming: I went with "old" and "new" conventions, but I agree that this may not be the most intuitive naming. I think we have three options:
   • Leave it to the Semantic Conventions SIGs to define the name (ideally one that is consistent across all semconv)
   • Use 'legacy' and 'stable' or maybe 'legacy' and 'v1'.
   • Some other naming proposal (I don't have a good alternative proposal)
2. What to do with experimental conventions/conventions outside of the first 'wave'. I don't think we have to fully define what happens with these on this RFC, it may be something that is affected by OTEP: Stable by Default opentelemetry-specification#4813, but we do need to have some idea of how to do it so that the solution does not end up conflicting with what we decide here.

Do you have a strong opiniong on either of these two? Are there any other big questions to resolve?

From my side:

1. For question 1, I am leaning towards changing 'old' and 'new' with 'legacy' and 'v1' respectively.
2. For question 2, I feel like the solution would be that these are all gated with an EmitExperimentalConventions feature gate per component.

[lmolkova]

For question 1, I am leaning towards changing 'old' and 'new' with 'legacy' and 'v1' respectively.
For question 2, I feel like the solution would be that these are all gated with an EmitExperimentalConventions feature gate per component.

sounds great, I really like 'legacy' / 'v1', it works especially well with the collector since it's on v0

[ChrsMark]

For question 1, I am leaning towards changing 'old' and 'new' with 'legacy' and 'v1' respectively.
For question 2, I feel like the solution would be that these are all gated with an EmitExperimentalConventions feature gate per component.

sounds great, I really like 'legacy' / 'v1', it works especially well with the collector since it's on v0

I like it too! Maybe instead of legacy/v1 we can go with v0/v1 which better aligns with the current versions of the Collector's components like hostmetricsreceiver, k8sattributesprocessor etc? It would be nice to have the feature gates in some sort of alignment with the component's version. This alignment won't enforce anything strictly though other than that the component will become v1 after its conventions are already v1 (with anything not included in v1 being considered as experimental).

Maybe we can consider including in this RFC the decided names for components like k8sattributesprocessor and hostmetricsreceiver already.

That being said, I think this RFC LGTM and once we finalise the naming I'll approve. Thank's again for putting this together @mx-psi!

[dmathieu]

I think we should have an explicit number of versions we keep the flag/duplicate conventions for.
To avoid the case where we yet removed the flag, and new breaking changes occur.

In otelhttp, we did the following:

• Add environment variable, no default change, wait for 2 versions
• Default to emitting both semconvs, wait for 2 versions
• Default to emitting only new semconvs, wait for 2 versions
• Remove environment variable

I believe a couple versions is fine for unstable components. Maybe 4 for stable ones?

[mx-psi]

@dmathieu Added some wording about the timeline, specifying 4 releases (8 weeks) for each. Does that seem reasonable? It's unclear to me what the equivalent should be in the Collector SIG to what the Go SIG does given the differences in release cadence.

Also, I would rather not make a distinction between unstable and stable components for this if that's okay with you and just put the more strict requirement for both (but if you think that's too stringent let's discuss)

[mx-psi]

cc @open-telemetry/collector-approvers We need at least two approvals for this since this is an RFC so I would like more feedback from approvers

[mx-psi]

@open-telemetry/collector-approvers This is entering final comment period, I will merge this on Monday, January 26th 2026 or after if there are no objections before then.