Metric definition: one rule, one number

Maya's dashboard says 6 active users on Wednesday 3 June; Theo's sheet says 7. The usual reflex is to hunt for the buggy query. Usually there isn't one.

"Active users on Wednesday" is a label. It sounds exact but leaves open every choice that moves the number:

• which action makes someone count: any event, or opening the app;
• what is counted: people, devices or rows;
• which accounts are left out, such as staff and test accounts;
• how long the window is and exactly when it starts;
• whose clock decides where Wednesday begins.

Maya counted anyone with any event on the UTC date. Theo counted app opens on each user's local date. Neither removed staff. Both queries are correct; they answer two different questions that share one name.

So when two numbers disagree, ask first what each one counted, not who made a mistake. And notice what a definition doesn't contain: the chart type, or whether the result is good. Those come after the number exists.

A metric definition nobody can misread has five parts, and each one closes a trap from the Halves data.

1. Qualifying action: the event that makes someone count. For "active", app_opened, not any event, because server-side recurring bills would make people look active.
2. Unit counted: distinct users, groups or settlements. Settle-ups are logged by both sides, so settlements are distinct settlement_id, not rows.
3. Exclusions: who is left out and how to find them: is_internal = true or acquisition_channel = staff, because one flag was left empty.
4. Time window: a day, a week or a month, with its exact start and end.
5. Reporting time zone: whose midnight splits the days, UTC or the user's.

Written together, the definition of DAU for Halves reads: distinct user_id with app_opened, staff excluded by flag or channel, one calendar day 00:00–23:59, UTC.

The same template works for any product metric. If two people can follow your definition and get different numbers, one of the five parts is still missing.

The time window says over which period the metric counts, and it needs an exact start and end, plus the time zone they're in.

A tempting shortcut is a window relative to now: "the last 7 days", "the past 24 hours". It's fine for a live monitor, but for a reported number it's a trap. The result depends on the moment someone runs the query. Run it on Thursday at 09:00 and at 17:00, and the windows differ by eight hours of data, so two people get two numbers, and nobody can reproduce last week's slide.

For reporting, use calendar windows: "Monday 1 June 00:00 to Sunday 7 June 23:59, UTC". Anyone, at any time, gets the same answer.

Two details to write down as well:

• where the week starts, Monday or Sunday; teams differ;
• whether the last period is complete. A week that ends tomorrow is still filling up, so its number will grow. Mark it as partial or leave it out of the chart.

With the definition fixed, recounting Wednesday is mechanical. The steps, in order:

1. Window and time zone first. In UTC, the date is exactly what event_time says, so keep rows from 2026-06-03T00:00 to 23:59.
2. Qualifying action. Keep only app_opened.
3. Exclusions. Look up each user_id in the users table and drop accounts with is_internal = true or acquisition_channel = staff: u019 and u002.
4. Unit. Count distinct user_id, so someone who opened the app twice counts once.

On 3 June in UTC, six users opened the app: u011, u002, u019, u004, u018 and u021. The two staff accounts opened it twice each. Remove them and 4 real users remain.

The order matters less than not skipping a step, but filtering the window first keeps the list short. A useful self-check is to count the same thing two ways: distinct users before exclusions minus the excluded ones that appear (6 − 2) should equal the distinct users after exclusions (4).

A reporting time zone decides whose midnight splits the days. Counting by the user's local date suits questions about daily habits and country campaigns, and it takes one extra step.

For each event, add the user's UTC offset to event_time and take the date of the result. In June: New York is UTC−4, Lisbon UTC+1, Kyiv UTC+3, Bangkok UTC+7.

• u012 in Bangkok opens the app at 23:10 UTC on 2 June: 23:10 + 7 h = 06:10 on 3 June. In.
• u017 in New York opens it at 01:40 UTC on 4 June: 01:40 − 4 h = 21:40 on 3 June. In.
• u011 in New York opens it at 02:30 UTC on 3 June: that's 22:30 on 2 June. Out.

With the same exclusions as before, local 3 June has 5 real users: u004, u012, u017, u018, u021. Check from the UTC count: 4 − 1 + 2 = 5.

Use the offset that applies on that date: summer time shifts many zones by an hour, so a fixed offset table must name its season.

When two dashboards disagree, the fastest way to end the argument is to reproduce each number from the raw data using the rule its author applied. If you land on their number, the data is fine and only the definitions differ.

For Maya's 6: take every row dated 2026-06-03 in UTC, whatever the event and whoever the user. There are 16 rows. Count distinct user_id among them: 6. That is her dashboard, exactly.

For Theo's 7: take app_opened, shift each time to the user's local clock, keep local 3 June and count distinct users, staff included: 7.

Now you can show the gap step by step instead of declaring a winner: "6 = any event, UTC, staff in; dropping staff gives 4. 7 = app opens, local date, staff in; dropping staff gives 5."

This also catches the rare real bug. If you follow someone's stated rule and can't reproduce their number, then something in their query differs from what they think it does, and that's worth fixing.

Stretch the same thinking from a day to the week of 1–7 June (UTC) and you get a ladder of numbers, each one a different definition:

• 22: distinct users with any event, nobody excluded;
• 19: only app_opened, which drops the 3 users whose only events were recurring bills created by the server;
• 18: also excluding is_internal = true, which removes u019;
• 17: excluding is_internal = true or acquisition_channel = staff, which also removes u002, whose flag was left empty.

Only 17 is the agreed DAU rule stretched to a week. The others aren't wrong numbers; they're answers to other questions, such as "how many accounts did anything at all?"

Two habits follow. First, when you see several versions of one metric, line them up like this and name the step that separates each pair; the gaps tell you what each team forgot. Second, put the definition under the chart as a caption. Then 17 on one slide and 22 on another can't both claim to be "weekly active users".

Definitions do change, and they should when a better rule appears: a new staff signal, a switch to local dates, a better qualifying action. The danger is the quiet change.

If DAU is counted by UTC dates until 30 June and by local dates from 1 July, the year's chart joins two different metrics. A jump at the switch may come from the rule, not from users, and readers can't tell.

Three safe ways to change a definition:

1. Recompute history with the new rule, so the whole chart uses one definition.
2. If you can't, mark the break on the chart and in the caption ("local dates from 1 July") and never compare across it.
3. For a while, report both versions side by side, so people see how much the rule alone moves the number.

In every case keep a dated changelog in the definition: what changed, when and why.

How it fits together: a number is its definition plus that definition's history: five parts, a fixed window, and a rule anyone can reproduce. Next, A tracking plan for a new feature designs the events those definitions need.