Measurement model
Poolstatis keeps definitions and observed data separate. Register the meaning first, activate it deliberately, then query accepted evidence.
Metric fields and lifecycle
| Field | Meaning |
|---|---|
key | Stable machine id used by Query DSL and MCP. |
name | Human-readable label. |
purpose | The product decision this metric informs; required and substantive. |
type | count, unique_actors, value, conversion, or state. |
source | Event/entity declaration, filters, value property, or conversion endpoints. |
category | Project-scoped purpose category from the production Cloud library. |
tags | Open, lower-cardinality feature or ownership facets. |
status | proposed, active, or deprecated. |
The production Cloud/Admin/API contract provides 16 system categories:
| Domain | System categories |
|---|---|
| Product | acquisition, activation, adoption, engagement, retention, referral, satisfaction |
| Business | revenue, cost, efficiency |
| Technical | quality, reliability, performance, delivery, security, data_quality |
Category answers why a metric exists. Namespaced tags such as
surface:checkout, component:api, channel:organic, and capability:export answer
where or what; a funnel answers which journey.
The pinned public npm runner @poolstatis/mcp@0.7.0 exposes the same category library
through list_metric_categories and category CRUD tools. Verify tools/list after any
future pinned runner upgrade rather than assuming parity.
Properties and trust
Event and entity properties are JSON inputs, but properties used for decisions should have a registered scope, type, purpose, and trust state. Low-cardinality enums make breakdowns stable. Do not turn unbounded URLs, user text, ids, or timestamps into dimensions.
Browser acquisition defines only bounded canonical fields such as $utm_source,
$utm_medium, $utm_campaign, $device_class, and trusted-proxy $country.
Session landing attribution is an association, not causal campaign credit.
People and identity
The current get_person MCP tool reads a behavior summary for one known distinct_id:
first_seen, last_seen, total and distinct events, active days, session count,
registered share, and bounded top events. If an identity entity exists, it also returns that
entity's current properties and update time.
This is a project/environment-scoped behavior summary, not a stored profile of arbitrary PII.
Its quality depends on a stable distinct_id and explicit anonymous-to-identified links.
Use get_person for one known distinct_id. The pinned public runner's
sample_events tool cannot filter by actor; do not use it as an unbounded people export.
Sessions, engagement, and bounce
Canonical Browser analytics currently reports real accepted visitors, sessions, and page
views. Session count is the number of distinct non-empty session_id values on canonical
page-view events.
The public @poolstatis/sdk@0.4.0 emits cumulative page.engagement lifecycle evidence.
Production Core deduplicates by page-view id and sequence, while the public
@poolstatis/mcp@0.7.0 runner reads foreground engagement, engaged sessions, bounce, and
coverage. Session span can include idle/background time and is not attention time. Missing
terminal lifecycle evidence remains incomplete rather than becoming a false zero or bounce.
Query acceptance
For every new metric:
- Send one real event with the project's
pk_key. - Confirm
acceptedand inspect per-element errors or unregistered warnings. - Review and activate the proposed metric.
- Run the typed query with explicit project, environment, range, and grain.
- Record missing coverage or truncation beside the result.
Continue with Metrics and purpose, Funnels, and Query DSL.