Instrumentation standard

This is the normative reference an agent follows when instrumenting a product. The job isn't "add tracking" — it's to make a product's behaviour computable: every number traces back to a declared reason.

Naming#

• Format object.action, lower snake_case: checkout.completed.
• Past tense for facts: completed, not complete.
• Name the intent, not the widget: export.requested, not button.clicked.
• $ is reserved for system events/properties.

Identity & properties#

1. distinct_id must be a stable user id — never per-session or random.
2. Money goes in a numeric amount with a currency. Never bake it into the name.
3. Mutable state belongs on entities, not copied onto every event.
4. Keep properties low-cardinality where you'll break down by them.

The north star#

Pick one north-star metric the whole product optimises, and instrument the funnel from acquisition to that metric first.

Anti-patterns#

• Vanity events with no metric or purpose behind them.
• Unstable distinct_id — silently corrupts every per-user number.
• State on events only — you lose "how many accounts are on Pro right now".
• Generic names (click, action, event) — unqueryable six months later.
• Tracking everything "just in case". Coverage is not the goal; decisions are.