Metric Trees
Every metric, traceable from formula to north star
Most tools treat a metric as a tile: a value, a sparkline, a name nobody quite agrees on. UPG treats it as a typed node with a formula, a role in the measurement system, a health state, and edges to everything it measures and everything that feeds it. Those edges turn a wall of dashboards into a tree a team can reason about: north star at the top, inputs at the leaves, and a traceable line between a number that moved and the work that moved it.
“A good metric changes the way you behave.”
What defines a metric
A metricmetricA unified metric that measures progress, health, or behaviour across the product carries its definition. It records what it measures (the action and the unit of analysis), how it is computed (a statistical_functionAggregation function applied to raw dataaverage · total · count · median · rate · ratio · percentage · score · min · max · p95 · p99 · growth_rate · conversion_rate · retention_rate · churn_rate · custom and a formulaCalculation formula or expression), and the role it plays through its designationRole this metric plays in the measurement systemnorth_star · kpi · driver · input · guardrail · proxy · health · vanity · metric: north star, driver, input, guardrail, proxy, or a vanity number to retire.
It also records where it sits and its current state: indicator_directionWhether this metric leads or lags the behaviour it measuresleading · lagging (leading or lagging), an AARRR or HEART metric_categoryAARRR or HEART category this metric belongs toacquisition · activation · retention · referral · revenue · engagement · happiness · task_success · adoption · other, a cadenceMeasurement cadence. Canonical `Cadence` since v0.4.0. `'realtime'` migrates to `'continuous'`; all other values 1:1.continuous · hourly · daily · weekly · monthly · quarterly · yearly · on_demand · other, a current value against a target, and a metric_healthUniversal health rollup. Orthogonal to lifecycle and `guardrail_status`. Applies to every metric regardless of `designation`. `healthy` = trending well against target / inside safe range. `at_risk` = drifting, approaching breach or target shortfall. `unhealthy` = missed target or breached; action needed. `unknown` = no current reading or not yet measured. For guardrails specifically, `guardrail_status` remains the breach-specific signal (`safe`/`warning`/`breached`).healthy · at_risk · unhealthy · unknownrollup. Every metric on this page shares that shape, so a query like “which lagging revenue metrics are at risk?” resolves to a filter over the graph.
actionThe action or behaviour this metric measures (e.g. "users who activated within 7 days")teams with 3 or more active members in a 7-day windowstatistical_functionAggregation function applied to raw dataaverage · total · count · median · rate · ratio · percentage · score · min · max · p95 · p99 · growth_rate · conversion_rate · retention_rate · churn_rate · customcountunit_of_analysisThe unit being counted or measured (e.g. "users", "sessions", "£")teamsformulaCalculation formula or expressiondistinct(team_id) where active_members >= 3cadenceMeasurement cadence. Canonical `Cadence` since v0.4.0. `'realtime'` migrates to `'continuous'`; all other values 1:1.continuous · hourly · daily · weekly · monthly · quarterly · yearly · on_demand · otherweeklycurrent_value : target1,240 : 2,000 teamsmetric_healthUniversal health rollup. Orthogonal to lifecycle and `guardrail_status`. Applies to every metric regardless of `designation`. `healthy` = trending well against target / inside safe range. `at_risk` = drifting, approaching breach or target shortfall. `unhealthy` = missed target or breached; action needed. `unknown` = no current reading or not yet measured. For guardrails specifically, `guardrail_status` remains the breach-specific signal (`safe`/`warning`/`breached`).healthy · at_risk · unhealthy · unknownat_riskownerPerson or team responsible for tracking this metric. Promote to a `node_owned_by_person` edge if ownership must be queryable.GrowthA metric carries its full definition as typed properties. The graph records what it measures (action, unit of analysis), how it is computed (statistical function, formula), where it sits (designation, impact level, leading or lagging), how often it reads (cadence), and its current state (current against target, metric health). Every metric on this page shares this shape.
The metric tree is one edge, used recursively
The metric tree is a single edge used recursively. A north star metricmetricA unified metric that measures progress, health, or behaviour across the product decomposes into the drivers that move it, and each driver decomposes into the inputs a team changes. Read upward, every input rolls up to the number at the top.
When an input shifts, the graph names the driver above it and the star it rolls up to. The connection between a leaf and the top-line number is explicit rather than assumed.
The tree is one edge applied recursively. A north star metric decomposes into the drivers that move it, and each driver decomposes into the inputs a team changes directly. Read the other way, every input rolls up to the number at the top, so a shift in a leaf is traceable to its effect on the star.
AARRR and HEART are groupings, not new entities
AARRR and HEART need no special entity. A metricmetricA unified metric that measures progress, health, or behaviour across the product carries a metric_categoryAARRR or HEART category this metric belongs toacquisition · activation · retention · referral · revenue · engagement · happiness · task_success · adoption · other, and the two best-known frameworks are canonical groupings of those category values: AARRR groups the funnel (acquisition, activation, retention, referral, revenue), and HEART groups the experience (happiness, engagement, adoption, retention, task success).
Tagged once, the metric appears in whichever lens reads that category. The same Weekly active teams counts as AARRR retention and HEART retention at once, because it is one node rather than a value duplicated across two reports.
A metric carries a metric_category, and the two most common frameworks are just canonical groupings of those category values: AARRR reads the funnel (acquisition, activation, retention, referral, revenue) and HEART reads the experience (happiness, engagement, adoption, retention, task success). A metric tagged with a category appears in whichever lens reads that category. The same Weekly active teams is AARRR retention and HEART retention at once, because it is one node rather than two copies.
Beyond decomposition: causal and guardrail edges
Numbers relate in more ways than decomposition. A leading metricmetricA unified metric that measures progress, health, or behaviour across the product drives a lagging one, so a team can act on the input before the lagging result lands. The edge records a causal claim that a flat KPI list leaves implicit.
A metric also guards another: a guardrail carries its own guardrail_statusCurrent guardrail health statesafe · warning · breached (safe, warning, breached), so that pushing one number cannot break another without warning. If raising activation breaches the unsubscribe guardrail, the status flips to breached as it happens.
indicator_direction: leadingmetricA unified metric that measures progress, health, or behaviour across the productindicator_direction: laggingmetricA unified metric that measures progress, health, or behaviour across the productdesignation: drivermetricA unified metric that measures progress, health, or behaviour across the productdesignation: guardrail / status: safemetricA unified metric that measures progress, health, or behaviour across the productMetric-to-metric edges carry the relationship between two numbers. Drives records that a leading input moves a lagging result, so a team can act before the result lands. Guards records that pushing one number must not breach another: the guardrail keeps its own guardrail status (safe, warning, breached), so a push on activation that breaches retention is recorded on the edge.
The metric that strategy resolves to
Strategy resolves to a metric. An outcomeoutcomeA desired business or user outcome and an objectiveobjectiveA strategic goal (OKR) are measured by it, a key resultkey_resultA measurable result tied to an objective is quantified by it, and a user-side desired outcomedesired_outcomeWhat the user hopes to achieve is quantified by it too.
Because one metric answers all of them, the OKR, the outcome, and the user need cannot disagree about whether progress happened. They share one measurement, so a review starts from an agreed number instead of reconciling several.
outcomeA desired business or user outcomeobjectiveA strategic goal (OKR)key_resultA measurable result tied to an objectivedesired_outcomeWhat the user hopes to achievemetricA unified metric that measures progress, health, or behaviour across the productA metric is the measurement layer the rest of strategy points down to. An outcome and an objective are measured by it, a key result is quantified by it, and a user side desired outcome is quantified by it too. One number answers all four, so the OKR, the outcome, and the user need read progress from the same source.
Where the number comes from, and whether to trust it
Provenance is part of the definition. The metricmetricA unified metric that measures progress, health, or behaviour across the product is defined by the data sourcedata_sourceA data source or integration that feeds it, so its formula traces back to a specific instrument.
Trust is recorded too. The metric is validated by a data quality ruledata_quality_ruleA data quality validation rule that flags a broken pipeline or stale data, and assessed by a metric quality assessmentmetric_quality_assessmentAn assessment of whether a metric is well-defined, measurable, and aligned to a meaningful outcome. that records whether a human has vetted the definition. A metric that has gone wrong is marked as such, not presented with the same confidence as a healthy one.
data_sourceA data source or integrationcadence: weeklymetricA unified metric that measures progress, health, or behaviour across the productdata_quality_ruleA data quality validation rulemetric_quality_assessmentAn assessment of whether a metric is well-defined, measurable, and aligned to a meaningful outcome.Provenance is part of the definition. The metric is defined by the data source that feeds it, so the formula traces to a named pipeline. It is validated by data quality rules that fail when the source breaks, and assessed by a quality assessment that records whether a person has vetted the definition. Trust in the number is recorded as a typed fact.
One metric, sliced by persona and segment
A headline number averages over groups that behave differently. A metricmetricA unified metric that measures progress, health, or behaviour across the product is segmented by the personapersonaAn archetype representing a user segment it describes and the behavioral segmentbehavioral_segmentA user segment based on behaviour it splits on, and a cohortcohortA group of users sharing a common characteristic is measured by it to follow one group over time.
The slices are edges on the same metric, not separate exports, so “weekly active teams, for mid-market, among power inviters” is one traversal of the graph. The cut and the whole are defined in the same place.
metricA unified metric that measures progress, health, or behaviour across the productpersonaAn archetype representing a user segmentbehavioral_segmentA user segment based on behaviourcohortA group of users sharing a common characteristicOne metric carries many slices. It is segmented by the persona it describes and the behavioral segment it splits on, and a cohort is measured byit to track one group over time. Because the slices are edges on the same metric, “weekly active teams, for mid-market, among power inviters” is a traversal over one node.
Why the metric earns its own entity
The same metric is referenced across the whole product. An experiment runexperiment_runAn execution instance of an experiment that records actual conditions, observations, and raw results. measures it, a dashboarddashboardAn analytics dashboard tracks it, a growth loopgrowth_loopA self-reinforcing growth cycle drives it, a service level objectiveservice_level_objectiveA service level objective (SLO) tracks it, a revenue streamrevenue_streamA source of revenue is measured by it, a customer health scorecustomer_health_scoreA composite health score for a customer is composed of it, and a forecastforecastA revenue forecast projects it.
Defined once, the number reads the same in every region. The metric is the shared point all of those references resolve to.
metricA unified metric that measures progress, health, or behaviour across the productexperiment_runAn execution instance of an experiment that records actual conditions, observations, and raw results.dashboardAn analytics dashboardgrowth_loopA self-reinforcing growth cycleservice_level_objectiveA service level objective (SLO)revenue_streamA source of revenuecustomer_health_scoreA composite health score for a customerforecastA revenue forecastSeven regions reference the same metric. Experimentation measures it, analytics tracks it, growth drives it, reliability tracks it, the business model measures revenue with it, customer success composes a health score from it, and sales projects it. The number is defined once, and every region reads the same node.
Build a metric, live
Everything above, in a live card. Every dropdown below is a real enum from the metric schema, and the card updates on each change. Set the designationRole this metric plays in the measurement systemnorth_star · kpi · driver · input · guardrail · proxy · health · vanity · metric and watch where the metric lands in the tree; set the metric_categoryAARRR or HEART category this metric belongs toacquisition · activation · retention · referral · revenue · engagement · happiness · task_success · adoption · other and watch its AARRR or HEART bucket move. The card is the metric schema itself, running in the browser.
count How many items match.
actionteams with 3 or more active members in a 7-day windowstatistical_functioncountformuladistinct(team_id) where active_members >= 3cadenceweeklycurrent : target1240 : 2000 teamsFrameworksAARRR and HEART
Tree roleSits at the top of the tree.
The form is generated from the metric entity schema, so every dropdown is a real enum from the spec. This is the same shape an SDK call would validate.
Metrics are the join between strategy and instrumentation. From the metric, the thread runs up into the cascade or down into the data:
The cascade above the metric: vision, objectives, key results, and the outcomes they serve.
The instrumentation below the metric: data sources, pipelines, dashboards, and quality rules.
The metric, its properties, and every edge it carries, in the entity reference.