Metric Definition and Implementation Questions

Direct answer: A metric is a quantitative measurement derived from data (a number that changes over time and can be tracked, like conversion_rate), a dimension is a categorical attribute you can slice a metric by (like user_country), and a KPI is a metric that has been elevated to a target with a business threshold attached (a metric someone is accountable for hitting a number on).

Structured elaboration:

• Metric vs dimension, concretely: page_view_count is a metric (a count you aggregate); user_country is a dimension (a label you group or filter the metric by, e.g., "page views BY country"). The same underlying event row contributes to both: the row itself is one page view (metric contribution), and it also happens to have been generated by a user in a specific country (dimension value).
• Metric vs KPI: conversion_rate is a metric whether or not anyone has set a target for it; it becomes a KPI when leadership says "we are targeting 4.5% conversion rate this quarter and someone owns hitting it." The same number, different organizational weight.
• Event-level vs aggregated: compute at event-level when the question is about individual occurrences (e.g., "which specific sessions converted"); aggregate to daily/user-level when the question is about a rate or trend over a population (e.g., "conversion rate this week").

Worked example: an e-commerce site logs a page_view event with user_id, country, page_type. page_view_count grouped by nothing is a metric (total volume); grouped by country uses country as a dimension to slice that same metric ("page views per country"); if leadership sets a target of "20% month-over-month growth in page views from a new market," page_view_count for that market becomes a KPI.

Trade-offs & pitfalls: Computing at the wrong level causes real bias: a conversion-rate metric computed at event-level (dividing total purchase events by total view events, both event counts) will be wrong if a single user can view the same page multiple times before converting once; that inflates the denominator relative to a user-level definition (unique purchasers / unique viewers), understating the true rate. The fix is not "always aggregate to user-level"; it's to be explicit about which grain the business question is actually asking, and to name that grain in the metric's documentation so nobody re-derives it inconsistently.

Direct answer: A metrics registry is a centrally maintained catalog that stores, for every business metric, its canonical name, plain-language definition, the exact calculation logic, an owner, and a last-updated timestamp, so that "active user" (or any metric) means exactly one thing everywhere it is used.

Structured elaboration: Minimum viable fields:

• Canonical name and a stable machine-readable ID (so dashboards reference the ID, not a re-typed name that can drift).
• Plain-language definition: a sentence a non-technical stakeholder can read and recognize as "yes, that's what we mean."
• Calculation SQL (or a pointer to the versioned model/query that computes it): the actual source of truth, not a paraphrase of it.
• Owner: an individual or team accountable for changes, not "the analytics team" generically.
• Freshness / last-updated timestamp: when the definition or its logic last changed, so a consumer can tell if a dashboard might be running on stale logic.
• Useful additions once the basics work: known caveats, upstream data-source dependencies (lineage), and a status (draft / approved / deprecated).

Worked example: a registry ROW for "Weekly Active Users" might read: name=weekly_active_users, definition="distinct users with >=1 qualifying event in the trailing 7 days, excluding bots/internal accounts", SQL=a link to the versioned dbt model, owner=product-analytics-team, last_updated=2026-06-01, caveat="bot-filter list is reviewed monthly and may lag new bot patterns." Anyone building a new dashboard queries this ONE definition instead of re-deriving their own "weekly active" logic, which is exactly the drift this registry exists to prevent.

Trade-offs & pitfalls: The hard part is not the schema, it is adoption: a registry nobody is required to use just becomes one more unmaintained wiki page. To convince skeptical stakeholders: (1) seed it with the metrics that ALREADY have known inconsistencies across teams, so the first thing people see solves a pain they already feel; (2) make the registry the thing BI tools and dashboards actually pull the calculation from (wire it in, don't just document it alongside), so using it is the path of least resistance, not an extra step; (3) assign real ownership with a lightweight approval step for changes, so the registry stays trustworthy rather than becoming stale documentation itself. A registry that is purely descriptive (a wiki page next to, not inside, the actual pipelines) tends to drift out of sync with reality within a quarter.

Direct answer: Define DAU as the count of distinct canonical users (coalescing signed-in user_id with an anonymous anon_id where no login exists) with at least one qualifying activity event in a UTC calendar day, after excluding bots and internal/test accounts and after deduplicating a user's activity across web and mobile into one canonical identity.

Structured elaboration, as the documentation would read:

1. User identifier: use user_id when signed in; when anonymous, use a durable anon_id (cookie/device ID), and if the same person later signs in, that is a KNOWN identity-merge event, not a new user, so historical anonymous activity should be attributable to the merged identity for retention analyses (though for a same-day DAU count, this rarely changes the number, since it's about distinctness within one day).
2. Qualifying events: name the specific event types that count (e.g., page_view, search, add_to_cart, purchase) rather than "any event," because some events (heartbeat pings, background sync) are not genuine activity and would inflate the count if included by accident.
3. Time window: a UTC calendar day, explicitly, with a documented note that this differs from "the user's local day" (see the timezone trade-off below).
4. Cross-device dedup: if a signed-in user is active on both web and mobile the same day, they count once; this requires the canonical-identity join described above, keyed on user_id, not on device or session.
5. Bots/test accounts: exclude via an explicit is_bot flag or a maintained internal-account allowlist, reviewed periodically since bot patterns change.
6. Documentation for reproducibility: publish the exact event-type list, the identity-merge rule, and one worked day's number with a manual audit trail so a stakeholder can re-derive it by hand on a small sample.

Worked example: a user signed in on mobile at 9am (a search event) and, later that same UTC day, browses anonymously on a shared work computer (a page_view event under a different anon_id, no login) would, under a naive identifier-per-row count, appear as two distinct "users" that day. The canonical definition above only merges them if there's an actual identity-linking signal (e.g., the anon_id was later associated with that account via a login on that device); absent such a signal, they are correctly counted as two different activity instances because the system genuinely cannot tell they're the same person from data alone; documenting that limitation explicitly (rather than silently overcounting or undercounting) is part of an auditable definition.

Trade-offs & pitfalls: UTC day boundaries are simpler to implement and keep partitioning simple, but they split a user's late-evening local activity across two UTC calendar dates for large parts of the world, understating single-day engagement for those users; user-local-day boundaries are more accurate to lived experience but require a timezone dimension on every event and complicate partition pruning. Pick one, document the choice, and don't silently switch mid-series (a switch changes the historical trend line's meaning without warning).

Direct answer: Tumbling windows are fixed, non-overlapping calendar periods (a calendar day, a calendar month); sliding windows roll continuously (a trailing 7-day average recomputed every day); session windows are defined by activity gaps rather than a fixed clock. Choose a rolling 7-day average over month-to-date when you want a stable, noise-smoothed trend that updates daily; choose month-to-date when the business genuinely cares about a fixed accounting period (billing, reporting cadence).

Structured elaboration:

• Tumbling: simplest to reason about and to partition (each period is independent, no overlap to recompute), but can produce a big visible jump at the boundary (day 1 of a new month resets to a small base) that isn't a real behavior change, just an artifact of the fixed window resetting.
• Sliding (rolling): smooths day-to-day noise and avoids the reset artifact, at the cost of being harder to partition efficiently (each day's output depends on a moving set of prior days) and being less intuitive to a stakeholder who thinks in calendar months for planning purposes.
• Session-based: appropriate when the metric is fundamentally about a unit of engaged activity rather than a fixed clock period (as in S23's conversion-rate-per-session); not a substitute for tumbling/sliding when the business question is genuinely calendar-anchored (e.g., "this month's revenue").
• Recommendation: a rolling 7-day average suits a noisy daily operational metric (e.g., daily active users, which has strong day-of-week seasonality) where the goal is trend-watching; month-to-date suits a metric tied to a business/billing cycle where the goal is a specific period's total, and where partial-period comparisons ("we're at 60% of last month's total on day 18") are themselves meaningful.
• Timezone/DST pitfalls: a tumbling daily window computed with fixed 24-hour arithmetic silently mishandles the DST transition day (23 or 25 real hours), either dropping or double-counting an hour of activity; use calendar-aware date truncation, not fixed-duration bucketing, to avoid this. A rolling 7-day window crossing a DST boundary has the same latent issue if implemented as now() - 7*24 hours instead of date subtraction of 7 calendar days.

Worked example: a DAU metric with strong weekday/weekend seasonality looks noisy and hard to eyeball as a raw daily tumbling number; a rolling 7-day average smooths that seasonality out and makes a genuine trend change visible days sooner than waiting for a full month-to-date comparison would.

Trade-offs & pitfalls: Don't silently switch between these mid-series; each produces a genuinely different-shaped line even for identical underlying data, and a switch reads as a step change in trend if not explicitly flagged in the metric's documentation and on the chart itself.

Direct answer: Detect every dashboard/model that reads the "purchase" event type (via lineage), decide explicitly whether historical data should be reprocessed under the new definition or left as a version boundary, version the metric definition rather than silently redefining it in place, and communicate the change with enough lead time that no stakeholder discovers it by noticing an unexplained trend break.

Structured elaboration, the plan:

1. Detect impacted dashboards: use the lineage documentation (S38/S58) to enumerate every metric/dashboard/model that reads event_type = 'purchase', rather than relying on informal knowledge of "who probably uses this," since an undocumented downstream consumer is exactly what gets broken silently.
2. Decide: reprocess historical data, or not: if the new schema is a genuine REDEFINITION of what counts as a purchase (not just a bug fix), reprocessing history under the new definition may be actively WRONG (it would misrepresent what was actually recorded/understood as a purchase at the time), whereas if it's a correction of an acknowledged error, reprocessing may be appropriate; this is a judgment call to make explicitly and document, not default silently either way.
3. Version the metric definition: the "purchase" metric gets a new semantic_version; historical dashboards spanning the change date get an explicit annotation marking exactly when the definition changed (S61's labeling practice).
4. Communicate: notify every identified downstream owner with the specifics: what changed, why, when it takes effect, and whether/how historical data is affected, with enough lead time for them to adjust any dependent alert thresholds or models before the cutover, not after.
5. Safeguards against downstream confusion: add a schema-contract test (S18) asserting the expected shape/values of event_type = 'purchase' events, so a FUTURE undocumented schema change to this same event type fails CI immediately rather than silently propagating another surprise redefinition.

Worked example: two SDK versions logging events under events_v1 and events_v2 schemas is a concrete instance of this exact problem: reconciling them requires a compatibility mapping (translating v1's "purchase" semantics to align with v2's, or vice versa) applied consistently at query time or via a unified view, rather than either silently ignoring the older schema's rows or silently treating both schemas as if they meant the same thing without verification.

Trade-offs & pitfalls: deciding NOT to reprocess history (treating the schema change as a forward-only version boundary) is often the safer default for a genuine semantic redefinition, since retroactively reinterpreting the past under a definition that didn't exist at the time it was recorded can itself introduce a new, subtle inaccuracy; but this must be a deliberate, documented decision made WITH the stakeholders who'll read the resulting discontinuous chart, not a default nobody chose on purpose.