Define what constitutes breaking changes for Metrics

[jsuereth]

We should outline what changes to metric streams (names, unit, type + attributes) constitutes a breaking change.

More details to follow

[jsuereth]

We'd like to tackle this question by focusing on what use cases for metrics should be preserved between OTEL instrumentation releases and expected interactions with schema_url / Telemetry Schemas.

For the first cut, we should investigate breaking behavior of:

• Alerts (and alert thresholds)
• Dashboards (common usage, simple queries)
• Analytics / "data lake"

[MrAlias]

Does this plan to change the semantic convention stability guidelines?

[jsuereth]

Yes. Specifically I want us to answer whether:

• We can/should rely on schema_url migrations for stability or ask for major version bumps when the absence of schema_url usage would lead to a breakage. (I.e. we consider schema_url an "aide" vs. a requirement for backends)
• Whether we loosen the definition of adding an attribute for metrics. Specifically adding an attribute that has the same value for all existing timeseries is actually a non-breaking change.
• Discussion/guidance around things like "split", changing "unit" type, etc.

[jsuereth]

Here's an unfinished document that walks through the problem of stability and how I'd like to think about it. I only had time to discuss Alerting instability of metrics, specifically when is it ok to add new attributes to a metric timeseries.

Welcome people's thoughts and opinions and more scenarios to tackle in that document as we go forward.

[jsuereth]

Updated a section for Metrics for our next meeting, including three topic points:

• Should we consider explicit bucket boundary changes on histograms breaking?
• Should we consider moving between integer / floating point values breaking?
• Should we consider moving between Attribute types where stringified values remain the same breaking?

I have my thoughts on each, but want to discuss in the WG.

[jsuereth]

From WG + Spec SiG:

Should we consider moving between integer / floating point values breaking?

We don't enforce this in the specification today, and doing so is likely breaking or lots of churn/work. We'd like to nuance what is considered breaking to something akin to:

• For a given timeseries, the type of points (integer / floating point) should remain the same for its lifetime.
• When merging timeseries, if different types of points are encountered (both integer and floating point) the resulting time series should be floating point.