Data model and scope
Poolstatis separates access, data, and environment boundaries so an agent cannot accidentally mix two products or production and test traffic.
Organization, project, and environment
| Boundary | What it owns | Practical rule |
|---|---|---|
| Organization | members, personal MCP tokens, commercial account | A pt_ token can discover projects only in this organization. |
| Project | events, entities, registry, funnels, experiments, Experience surfaces | Use one project for one independently governed product data boundary. |
| Environment | the runtime slice selected by the ingest key and query | Keep prod, staging, and development evidence separate. |
An ingest pk_ key is bound to one project and environment. An sk_ token is bound to one
project. A personal pt_ token is organization-wide, but every read or mutation still names
a project. Tenant checks are server-side; a slug is not authorization.
Events, actors, and entities
- An event is an immutable fact: an actor did something at a timestamp. Its grain is one occurrence, not one user or session.
distinct_ididentifies the actor within a project and environment. Use a stable product-side id. Anonymous and authenticated ids require an explicit trusted identity link; Poolstatis does not guess that two ids are the same person.- An entity is mutable current state such as an account plan or document status. Entity upserts merge supplied properties; they are not an event history.
- A session is an optional opaque
session_idattached to events. Session count is not visitor count, and a session is not an authenticated user.
Do not send email, names, form values, or other arbitrary personal data just because the
properties object accepts JSON. Keep ids opaque and define the purpose of every property
used for measurement.
Metrics, funnels, and query results
A metric is a registry declaration over events or entities. It includes a
mandatory purpose, a source, a type, status, category, and tags. Query tools reference the
metric key rather than exposing raw SQL.
A funnel is an ordered list of registered metrics plus a mandatory goal and conversion
window. A trend, retention table, lifecycle result, or other query response is observed
evidence at a stated grain and time range; it is not automatically a causal insight.
Experiments and Browser Experience
An experiment measures an active feature flag against a registered outcome metric and guardrails. Deterministic assignment and exposure are separate from the outcome. Do not call a difference causal until the experiment's own quality gates are satisfied.
Browser Experience stores privacy-bounded labelled clicks, scroll milestones, safe route
keys, and coarse client errors. Layout-accurate maps additionally require an immutable
surface + route + version + device + env screenshot. These aggregate signals remain separate
from the explicit-consent Session Replay recorder and retention store.
Grain checklist
Before accepting a number, state all five:
- Unit: event, actor, session, entity, or experiment exposure.
- Project and environment: the exact data boundary.
- Time window: including timezone and interval.
- Population: filters, identity rules, and consent coverage.
- Evidence quality: registered share, missing lifecycle signals, truncation, and warnings.
Next: Measurement model.