Developer/Analytics/EventTracking/Fundamentals/event-tracking-plans-and-naming-conventions

Event Tracking Plans and Naming Conventions

Concept

A tracking plan (also called a data dictionary or event taxonomy) is the document — ideally a machine-readable schema, not just a spreadsheet — that enumerates every analytics event a product emits: its name, the properties it carries, the type and allowed values of each property, and which team owns it. It is the contract between the engineers who instrument events and the analysts/PMs who query them downstream. Without one, the same real-world action ends up logged under several different names by different engineers (signup, SignUpCompleted, user_registered), and analysts burn time reverse-engineering which event actually means what before they can trust a single number.

The dominant naming convention, converged on independently by most analytics platforms, is object-action in past tense, snake_case: order_completed, search_performed, invite_sent — a noun (the thing acted on) followed by a verb describing what happened to it, always past tense since an event is a record of something that already occurred. The single hard rule underneath this: event and property names must be fixed strings baked into the code, never generated dynamically from runtime data. Variable information (which product, which search query, which invite recipient) belongs in the event's properties, never interpolated into the event name itself — product_viewed with a product_id property, never a distinct product_viewed_42 event per product. Violating this turns what should be one event with a filterable property into an unbounded, ever-growing set of near-duplicate event names that no dashboard can meaningfully aggregate.

A tracking plan also has to bound how many distinct events exist. Every event added is a permanent maintenance burden — someone has to keep it correctly instrumented as the codebase changes — so the discipline is choosing events that map to metrics someone will actually query, not logging every UI interaction "just in case." Amplitude's own field guidance puts a healthy plan somewhere between roughly 10 and 200 distinct event types for most products: too few and funnel/retention analysis can't distinguish meaningfully different user actions; too many and the plan itself becomes something no one can hold in their head, which is when naming drift and duplicate events start creeping back in.

Tradeoffs

Approach	Benefit	Cost
No formal tracking plan (engineers name events ad hoc)	Zero upfront process cost, fastest to ship a single event	Naming drift across the team; analysts can't trust event names mean what they think; near-duplicate events accumulate
Tracking plan as a shared spreadsheet/doc	Cheap to start, visible to non-engineers (PM, analytics)	Drifts from the actual code silently — nothing enforces that what's implemented matches what's documented
Tracking plan as a versioned schema wired into CI (e.g. JSON Schema validated at build or ingest time)	Drift is caught automatically — a mismatched event fails a check before it ships	Real upfront investment: schema tooling, validation step in the pipeline, and a review process for schema changes
Track everything (maximal instrumentation)	Never miss data you'll wish you'd captured	Bloats the plan past the point analysts can navigate it; increases the chance of leaking sensitive data into event properties by accident
Track a minimal, deliberately chosen set of events	Plan stays small enough to fully understand and query with confidence	Requires deciding upfront which questions matter — a metric nobody thought to instrument for is unavailable retroactively

When to use / when not to

Write a tracking plan before instrumenting anything beyond a handful of events — retrofitting naming consistency onto events that are already shipped and already have historical data under the old names is far more expensive than establishing the convention first.
Favor a schema wired into the build or ingestion pipeline over a plan that lives only in a spreadsheet once more than a couple of engineers are shipping events — a spreadsheet has no mechanism to catch drift, and a plan nobody trusts is worse than no plan, since it actively misleads analysts into thinking the documented shape is the real one.
Don't instrument an event just because it's technically easy to capture; instrument the events a specific funnel, retention curve, or business metric actually needs. Start from the metric and derive the event, not the other way around.
For a very early-stage product with a handful of screens and one or two people looking at the data, a lightweight spreadsheet plan is proportionate — the CI-enforced schema is worth building once enough people are shipping events that human review alone can't catch drift.

Common pitfall

Letting event names encode variable data (product_42_viewed, search_query_shoes_clicked) instead of putting that data in properties. This is easy to do under deadline pressure because it feels like "more specific" tracking, but it silently breaks every aggregate query: a funnel or count that should group all product views together now has to know about every product ID that has ever been instrumented, and new values keep appearing as new "events" instead of new rows for an existing event. The fix is mechanical once named — audit for any event name containing what looks like an ID, category, or free-text value, and move it into a property — but the pitfall itself is subtle enough that it recurs across teams that haven't hit it before.

Engineering Lens

The tracking plan is infrastructure, not documentation — treat a proposed new event the way you'd treat a proposed new API endpoint or database column: does it duplicate something that already exists under a different name, does its naming follow the established convention, and does it belong to a metric someone has actually asked for. The real cost of a bad tracking plan rarely shows up as a broken pipeline; it shows up months later as a stakeholder distrusting a dashboard number because two different engineers instrumented "the same" business event slightly differently, and reconciling that after the fact requires a data audit across every consumer of both event names.