Metrics and the semantic layer
In Torno, a business number is defined once. A Metric is a named, typed, versioned definition, and every consumer — funnels, Experiments, the Needle, the CLI — reads it through the same envelope. This page covers the definition model, what the envelope carries, and how uncertainty renders.
Definitions, not ad hoc queries
A Metric definition carries a Property-unique key, a display name, a class (standard or revenue), a typed source binding, unit, currency, and decimals, point-in-time or windowed semantics, supported grain, filters, and declared decompositions. Versions are immutable and require change notes, so every number can say exactly which definition produced it.
A built-in catalog covers MRR, activation rate, D30 retention, signup conversion, and CAC. Each can be instantiated exactly once per Property — there is no second, slightly different MRR.
Guardrail sets associate active Metrics with a harm direction, so Loops and Experiments know which way is bad.
The one-number contract
The Metric layer is the only place a named business number is defined or read. Other parts of the product register source providers or compose results; none computes its own version of MRR, conversion, or retention. The funnel view, an Experiment readout, the Loop board, the Needle, and the CLI subscribe to the same persisted readout. If two surfaces disagree, that is a bug in Torno, not a modeling debate.
The read envelope
Reading a Metric returns an envelope, never a bare number:
| Envelope field | What it tells you |
|---|---|
| Value and unit | The number, in the definition’s unit, currency, and decimals. |
| Status | pending, no data, below k, source unavailable, error, stale, or ready — plus a reason when evidence is insufficient. |
| Bounds | The uncertainty range when the value is an estimate. Provisional windows are flagged. |
| Source basis | Which provider produced the value: event and Cohort aggregation, funnels, Experiments, revenue, or ad costs. |
| Definition version | Exactly which immutable version computed it. |
| Environment, window, timezone | The scope of the read. |
| Freshness | When the underlying data last refreshed. |
| Series | The time-series cells behind the headline value. |
| Decomposition | An optional declared breakdown that reconciles to the total. |
Honest states, never zeros
- A source with no observations reads as no data — a different thing from a measured zero, and rendered differently everywhere.
- A readout over too small a population reads as below k and is suppressed under the privacy floor (k=25 by default). Suppressed cells stay suppressed when composed into larger numbers.
- A failing provider reads as source unavailable or error, and stale data is labeled stale. None of these ever becomes a zero.
- Estimates keep their bounds through composition rather than shedding them.
Revenue targets and leading indicators
Revenue moves slowly, which makes it a poor steering wheel on its own. A leading-indicator pairing connects a lagging revenue-class Metric to a faster steering Metric. Loops and the Needle resolve the same pairing, and a Loop targeting a revenue-class Metric must have one before it can be created.
Watches
A Metric watch evaluates a band or delta condition after each refresh and emits one metric_delta Signal per firing — this is how Metrics wake Loops. Scheduled refreshes heal stale watched and targeted Metrics, so watches evaluate against current values.
Working with Metrics
The web catalog supports browsing, typed create and edit, version history, preview, archive and restore, pairings, and guardrail sets. The same definition, read, pairing, guardrail, and watch operations are exposed through the API, the CLI, and MCP tools — see the agent interface. The CLI returns the full envelope, not a simplified number:
torno metric get mrrHonest notes
A Metric is only as honest as its source. The envelope’s source basis and freshness fields say where a number came from and how current it is; when the source is an external connector or import, Torno reports what the provider returned rather than vouching for the provider. The semantic contract — one definition, one envelope, honest states — holds either way. For how these numbers appear in funnels and reports, see Analytics.