---
title: "Define each metric once · Agent Wranglers"
url: https://agentwranglers.se/playbook/analytics/events-and-metrics/metric-definitions
id: ANA-5
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1042
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Define each metric once

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Events and metrics](https://agentwranglers.se/playbook/analytics/events-and-metrics.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: ANA-5
- Level: Recommended
- Chapter: [Events and metrics](https://agentwranglers.se/playbook/analytics/events-and-metrics.md)
- Rule: Define every business metric once, in version control, and build every dashboard and report from that definition.
- 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.
- How: 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](https://agentwranglers.se/playbook/documentation/keeping-docs-current/one-home-per-value.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### SQL example

```sql
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

```js
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

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

## Related rules

- DEN-3 [Build every warehouse table from reviewed code](https://agentwranglers.se/playbook/data-engineering/warehouse-and-models/transformations-as-code.md) in Data engineering
- SUP-36 [Count contacts per thousand active customers](https://agentwranglers.se/playbook/customer-support/measuring-support/contact-rate.md) in Customer support
- ANA-4 [Keep test and bot traffic out of the numbers](https://agentwranglers.se/playbook/analytics/events-and-metrics/exclude-test-traffic.md) in Product analytics and experiments
- DOC-47 [State each value in one document and link to it](https://agentwranglers.se/playbook/documentation/keeping-docs-current/one-home-per-value.md) in Documentation
- ANA-6 [Measure how many new accounts reach their first result](https://agentwranglers.se/playbook/analytics/events-and-metrics/activation-rate.md) in Product analytics and experiments
- ANA-15 [Stop an experiment when a guardrail metric breaks](https://agentwranglers.se/playbook/analytics/experiments/guardrail-metrics.md) in Product analytics and experiments

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/analytics/events-and-metrics/metric-definitions">Agent Wranglers product analytics and experiments playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Keep test and bot traffic out of the numbers](https://agentwranglers.se/playbook/analytics/events-and-metrics/exclude-test-traffic.md)
- Next: [Measure how many new accounts reach their first result](https://agentwranglers.se/playbook/analytics/events-and-metrics/activation-rate.md)
- [Events and metrics](https://agentwranglers.se/playbook/analytics/events-and-metrics.md)