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
The production Cloud library groups purpose into Product, Business, and Technical categories.
The pinned public npm runner @poolstatis/mcp@0.7.0 exposes
list_metric_categories plus category CRUD and accepts the production category library.
Check tools/list after upgrading a pinned runner; do not assume future parity.
Product categories include acquisition, activation, adoption, engagement,
retention, referral, and satisfaction; Technical includes quality,
reliability, performance, delivery, security, and data_quality.
Use one category for why the metric exists. Use namespaced tags such as
surface:checkout, component:api, channel:organic, or capability:export for
where/what, and use a funnel for a journey.
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).