Conventions Evolve: Handling Breaking Changes

The Migration Challenge

Semantic Conventions are a living specification. As the OTel community learns more about what works in practice, attribute names get renamed, split, or deprecated. This is not a flaw — it reflects the maturity of the standard — but it creates a real operational challenge.

A real example: The HTTP convention migration

In OTel Semantic Conventions v1.20 and earlier, the HTTP attributes were http.method, http.status_code, and http.url. In v1.21+, these were renamed to align with a new, more consistent naming scheme: http.request.method, http.response.status_code, and url.full.

If your dashboards and alerts are built on http.method and your instrumentation library upgrades to emit http.request.method, your dashboards silently break.

Strategies for managing convention migrations:

1. Pin your semconv package version. Don't auto-upgrade. Review the changelog before upgrading — pinning the exact package version in your dependency manifest, rather than accepting the latest release automatically.

2. Use the Collector to emit both old and new attributes during migration. The transform processor can copy a value to both the old and new key simultaneously, giving you time to update dashboards before removing the old key.

3. Version your dashboards alongside your semconv version. Tag dashboards with the semconv version they were built against.

4. Use the OTel schema URL. Resources can declare which version of the conventions they conform to via the telemetry.sdk.version attribute and the schema URL field. Some backends use this to auto-translate between versions.

The key insight for senior engineers: semantic convention migrations are a schema migration problem, not just a naming problem. Treat them with the same rigor you would apply to a database schema migration — with a transition period, backward compatibility, and a rollback plan.