Semantic Conventions and release strategy

[bryannaegele]

The Semantic Conventions spec introduced a significant breaking change (opinion) to the HTTP Tracing spec's span name conventions in v1.18, along with a number of other breaking changes in v1.20. This was recognized as a disruptive change for endusers by several maintainer groups and the spec wg decided that the languages should hold off on implementing that version until the http section of the semantic conventions spec was marked stable. This evolved into a broader migration plan for semantic convention adoption choices by end users across the entire spec.

~Open question~ on the http span name issue. Resolution: HTTP span names are included in the "should not change until HTTP conventions stabilized" plan. Clarified in this open PR

Summary of the determinations that have come out of these plans:

• Libraries should implement and respect the OTEL_SEMCONV_STABILITY_OPT_IN env var
• v1.20 is generally considered as the start of this stable/unstable cutoff for a number of attributes.
• SHOULD NOT change the version of the HTTP or networking attributes that they emit until the HTTP semantic conventions are marked stable (HTTP stabilization will include stabilization of a core set of networking attributes which are also used in HTTP instrumentations). (My understang - This should therefore supersede stable/unstable status for those attributes)
• For a user opting into http/dup, where a conflict exists between stable/unstable, the stable version should be emitted.
• SHOULD maintain (security patching at a minimum) the existing major version for at least six months after it starts emitting both sets of attributes.
• SHOULD drop the environment variable in the next major version (stable next major version SHOULD NOT be released prior to October 1, 2023).

Reference the following resources for any questions when dealing with semantic convention updates:

• https://github.com/open-telemetry/opentelemetry-specification
• CNCF Slack #otel-semantic-conventions-wg channel

This raises some open questions:

• Should we:
  • make an effort to release each semantic convention version so these changes are incremental and which a user could override?
  • continue to just do sporadic semcon library releases and add deprecation notices over a period of time? Incremental vs rip off the band-aid before something is marked stable
• How do we track stable vs unstable attributes? Introduce a map in semconv that tracks the statuses that can be referenced by libraries?
• How do we address the security patching requirement? Branch from the tag which needs the patch and publish?

[bryannaegele]

https://github.com/open-telemetry/semantic-conventions/pull/278 has been merged to clarify confusion on breaking changes.