Metric Definitions That Scale

• Structure a metric definition: measure, dimensions, filters, grain
• Make definitions testable and versioned
• Design metrics that compose into KPIs and time comparisons

• Spreadsheet-era habits (define it again in each workbook) do not survive 20 dashboards.
• Composable definitions enable self-service without turning users loose on raw data.
• Versioned definitions make changes auditable — you can see why a number moved.
• Tests catch the classic 'it worked locally' definition bugs before they hit production.

You don't rewrite sort() per application; you import the tested, versioned one. Metrics are the functions of the business — write and test them once, import everywhere, upgrade in tandem.

• The definition declares the numerator measure, the population (denominator scope), the allowed dimensions and the mandatory filters.
• It specifies grain (per-order, per-day, per-user) and an as-of rule (event time vs processed time).
• It composes: base metrics (revenue) feed derived metrics (revenue per user) and KPIs (vs target).
• Tests assert known values, null behavior, and grain stability on every change.
• Versioning stores the definition history, and the catalog records owner and certification.

• A metrics catalog defines revenue once; finance, sales ops and exec dashboards all reference it, and a change is versioned with a reviewer.
• A KPI library composes base metrics into retention cohorts and weekly targets without duplicating base calculations.
• CI tests validate the metric against a fixture dataset on every merge, so a 'quick edit' can't silently change headline numbers.

• Write definitions as data (name, formula, scope, owner), not as prose to be re-implemented.
• Version every change and require a test that asserts a known value.
• Compose from base metrics; avoid re-deriving a base metric inside a KPI.
• Document as-of timing and currency/timezone assumptions in the definition.

• Copy-pasting metric expressions into each report 'temporarily' — the permanent fork.
• Versioning the dashboard but not the metric, so rollbacks are impossible.
• No tests: a renamed column silently changes a headline number.
• Defining metrics in tools that can't be version-committed (some GUI-only setups).

• When a metric moves unexpectedly, diff the definition history first, then the data.
• Test at the seam: assert the metric against a tiny fixture where you know the answer.
• Check composability — if a KPI doubled because it recomputed a base metric with a new filter, that's the bug.