smolanalytics
menu
instrumenttrusthow it worksdocsfeaturespricinggithub
log inStart free
glossary · analytics term

What is a tracking plan?

The agreed spec of every event you record, the contract that keeps your funnels and retention curves built on events that fire the same way everywhere.

A tracking plan is the single agreed specification of every event a product records: each event's name, the properties it carries, their types, and what it means. It is the contract that keeps analytics consistent, so a funnel or retention report is built on events that fire the same way everywhere, instead of names that drift as different people add tracking. Without a plan, event names splinter (signup, sign_up, Signup), properties go missing on half the calls, and two people instrument the same action two different ways, so the numbers stop agreeing and nobody trusts the dashboard. A tracking plan fixes that by naming the events and properties once, up front, as the source of truth everyone codes against. The weak version is a spreadsheet: it drifts out of sync with the code the day someone ships an event the sheet never mentioned. The strong version is plan-as-code: the plan lives in your repo as a committed file, and a checker compares it against both the code (does the code still match the plan?) and real traffic (are the events actually firing, are unexpected ones showing up?), failing the build when they diverge. That divergence is called drift, and plan-as-code turns drift from a slow data-quality rot into a build error you fix immediately. The plan is what makes every downstream number, funnel, retention, cohort, trustworthy, because a report is only as correct as the events feeding it, and the plan is what guarantees those events.
what it contains

What goes in a tracking plan

A tracking plan is not long, it is precise. For every event you intend to record, it pins down:

  • ·The event name, exactly, so signup_completed is the name and sign_up is not a silent second event.
  • ·The properties it carries and their types (plan: string, amount: number), so a breakdown you want later is actually possible.
  • ·What it means, one line, so two people instrument the same action the same way instead of inventing two events for it.
the failure mode

Drift, and why plan-as-code beats a spreadsheet

The reason plans fail is drift: reality slowly stops matching the plan. A new event ships that the plan never listed. An event stops firing but is still expected. A property gets renamed. Nothing breaks loudly, so nobody notices, until three months later the funnel has holes and the dashboard has lost everyone's trust.

A spreadsheet cannot stop any of this, it is documentation, not enforcement, and it goes stale the day someone ships an event it never mentioned. Plan-as-code puts the plan in the repo where a checker can act on it: compare the plan to the code, compare it to live traffic, and fail the build when they diverge. Drift stops being slow data rot and becomes a build error you fix in the same PR that caused it.

how smolanalytics does it

A committed plan with drift gates, plus an agreement test

smolanalytics keeps the tracking plan as a committed file and enforces it two ways:

plan check --code: static: does the code still match the plan?
plan check (traffic-based): are the planned events actually firing, and are unexpected ones showing up?
plan sync: reconcile the plan with what the code and traffic actually do

The plan keeps your events clean. A second, stronger guarantee keeps your answers clean: a CI agreement test asserts that the AI's answer equals the /v1 API equals the dashboard, byte for byte. So a number cannot be hallucinated: if the ask-bar answer ever drifts from the API or the dashboard, the build fails. Every answer also ships a computed_by receipt, the exact deterministic report and scope behind it, so you can see why a number is what it is.

This pairs with event instrumentation: the agent writes and verifies the events, the plan keeps them from drifting. See every feature.

Common questions

What is a tracking plan in simple terms?
It is the master list of every event your product should send, what each one is called, what properties it carries, and what it means, agreed once so everyone instruments the same way. Without it, event names drift and properties go missing, and your funnels and retention curves quietly stop being trustworthy. The plan is the contract that keeps the data clean.
What is plan-as-code?
Plan-as-code means the tracking plan lives in your repo as a committed file, not in a spreadsheet. Because it is in the codebase, a checker can compare it against your actual code and against live traffic, and fail the build when they disagree. A spreadsheet drifts out of date the moment someone ships an event it never mentioned; a committed plan is checked on every change, so it stays true.
What is event drift?
Drift is when your real events stop matching the plan: a new event ships that the plan never listed, an event stops firing but is still expected, a property gets renamed, or a name splinters into variants. Drift is how analytics rots slowly, no single change breaks anything, but months later the numbers are full of holes and nobody trusts them. Drift gates catch each divergence at the moment it happens instead.
Why not just use a spreadsheet for the tracking plan?
A spreadsheet is fine as documentation but it cannot enforce anything. Nothing stops a developer from shipping an event the sheet never mentioned, and nobody updates the sheet when they do, so within weeks it describes a product that no longer exists. Plan-as-code puts the plan where the checker can act on it, comparing it to code and traffic and failing the build on divergence, so the plan and reality can't quietly part ways.
How does smolanalytics enforce the tracking plan?
The plan is a committed file, and there are two checks: plan check --code (static, does the code still match the plan?) and a traffic-based check (are the planned events actually firing, are unexpected ones appearing?), plus plan sync to reconcile. On top of that, a CI agreement test asserts the AI's answer equals the /v1 API equals the dashboard, byte for byte, so a number can never be hallucinated. The plan keeps events clean; the agreement test keeps the answers honest.
Start the 14-day trial
no credit card · or self-host free forever (MIT)

keep reading

event instrumentation
getting the planned events to fire
what is autocapture?
the zero-code data floor
every feature
plan-as-code, drift gates, agreement test