Metric versioning is the practice of assigning a version to each metric definition and recording which version produced each stored value. It is the mechanism that makes a long time series interpretable after the inevitable happens and the formula has to change.
Legitimately, and often. A source tool is replaced and the new one exposes a better field. A regulator specifies a calculation you were doing differently. A scope error is discovered. A severity taxonomy is revised. An acquisition brings in a population that has to be handled explicitly.
The question is never whether definitions change. It is whether the change is recorded.
The ability to answer how a figure from two years ago was calculated, which is the question that arrives during audits and supervisory reviews.
The ability to distinguish a genuine change in the world from a change in method when a series steps.
The ability to recompute history under a new definition, because the old and new formulas both exist as specifications rather than one having overwritten the other.
Without versions you have a chart. With them you have a record.
Borrow from semantic versioning.
A major increment for anything that changes what the metric means: scope, population, unit, direction. Values across a major boundary are not comparable without restatement.
A minor increment for changes that refine without altering meaning: a new source added, an edge case handled explicitly.
A patch increment for corrections that fix an error in implementing the stated definition.
The useful part is the major boundary. It tells a reader where the series can and cannot be compared.
When a definition changes materially, choose one of three and record which. Recompute the history under the new definition. Keep both series and show the break. Or start a new metric and retire the old one.
Doing none of the three and simply carrying on is what produces definition drift.
Metric Maestro versions definitions in the registry and stamps every computed value with the version that produced it.
Because the source records are retained rather than only the results, a definition change can be applied backward across the stored history, so you can see what the last three years would have looked like under the new formula before deciding whether to restate.
From the blog