Define each metric once

How to do it

Write the definition as code or SQL with a name, owner, formula, filters and time zone. A semantic layer such as dbt's MetricFlow or Cube does this, or a folder of reviewed SQL views. "Active user" must mean the same in every chart, for example "signed in at least once in the last 28 days". Change a definition through review, and note the change date on charts. It is the analytics side of State each value in one document and link to it.

Examples

SQL example

CREATE VIEW metric_weekly_active_users AS
SELECT date_trunc('week', received_at AT TIME ZONE 'UTC') AS week,
       count(DISTINCT anonymous_id) AS weekly_active_users
FROM events
WHERE name = 'session_started' AND traffic = 'visitor'
GROUP BY 1;

JavaScript example

export const METRICS = {
  weekly_active_users: { owner: 'product', view: 'metric_weekly_active_users', definition: 'Distinct analytics IDs with session_started in an ISO week, UTC' },
};

Python example

METRICS = {
    "weekly_active_users": {"owner": "product", "view": "metric_weekly_active_users",
                            "definition": "Distinct analytics IDs with session_started in an ISO week, UTC"},
}

How to check

A script lists every saved dashboard query and fails on any that computes a named metric without the shared view or metric. Two dashboards showing the same metric for the same day show the same number.

Related rules

• DEN-3 Build every warehouse table from reviewed code in Data engineering
• SUP-36 Count contacts per thousand active customers in Customer support
• ANA-4 Keep test and bot traffic out of the numbers in Product analytics and experiments
• DOC-47 State each value in one document and link to it in Documentation
• ANA-6 Measure how many new accounts reach their first result in Product analytics and experiments
• ANA-15 Stop an experiment when a guardrail metric breaks in Product analytics and experiments