Metrics & purpose
A metric is a registry declaration: what to measure, and why.
Required fields
Every metric needs a key, name, type, source, and a non-empty purpose. The server
rejects empty or templated purposes — this is the core of the product, not boilerplate.
Types
| type | answers | source shape |
|---|---|---|
count | how many times did X happen | { event, filters? } |
unique_actors | how many distinct users did X | { event, filters? } |
value | sum/avg/p90 of a numeric property | { event, value_property, agg } |
conversion | what share went A → B in a window | { from, to, window_seconds } |
state | how many entities are in state S | { entity_type, filters, agg } |
Categories and tags
Tag each metric with one AARRR category — acquisition, activation, retention, revenue,
referral — or quality. Beyond that, add free-form tags (lowercased, multiple) for the
product feature a metric belongs to: ["checkout"], ["onboarding", "north-star"]. Tags are
how you later group metrics by feature without a rigid enum.
There is no deployed custom category taxonomy or separate technical category in this
contract. Use quality for a real quality outcome and tags such as ["performance"] or
["reliability"] for additional grouping. Do not document a technical metric library until
the full taxonomy is integrated.
Lifecycle
Metrics start as proposed. The owner activates them — only active metrics mark matching
events as registered on ingest. Retire metrics as deprecated; never delete (historical
queries must keep working).