Event taxonomy for product analytics.

List the questions before the events

Write down the six to ten questions the business has to answer every month. Activation rate, week four retention, which plan upgrades, where support load comes from. Each question names the actions that prove an answer.

• One page, one owner per question, no dashboard talk.
• Any event that answers no question is not an event yet. Park it.
• This step decides scope, which is the part teams skip and then regret.

Pick one naming convention and write it down

Object plus past-tense action, in snake case: checkout_completed, report_exported, invoice_failed. The convention belongs in the repo, not in someone's memory.

• Keep a short, closed list of allowed actions: created, completed, failed, viewed, clicked, invited, upgraded, cancelled, exported.
• Never encode context in the name. Context is what properties are for.

Define the property schema once

Two tiers. Global properties attached to every event, and properties specific to one event. The global tier is what lets you compare anything to anything later.

global:    user_id  account_id  plan  role  app_version  source
checkout: cart_value  currency  item_count  payment_method  coupon_code
report:   report_type  row_count  export_format  duration_ms

• Property names are snake case nouns. Units live in the name: duration_ms, not duration.
• Use closed enums for anything you will group by. Free text becomes a reporting problem in week two.
• Never send email addresses, names, or message bodies. Hash identifiers where you need to join across systems.

Draw the line between event, property, and state

A new event earns its place only when it answers a new question. If the question is the same and only the circumstances differ, it is a property.

Version and deprecate, never silently rename

Additive changes are free: a new optional property breaks nothing. Breaking changes get a version and a migration window.

• New shape: checkout_completed_v2, dual fire for one release, then retire the old name on a stated date.
• Keep a deprecation log: event, date, owner, replacement, last date it fired.
• Renaming an event in place rewrites history. Every chart built before the rename becomes a lie.

Assign an owner and a review gate

Taxonomy without ownership drifts within one quarter. Name one owner, usually product analytics or product operations, and make them a required reviewer on instrumentation changes.

• Every instrumentation pull request carries the event name, its properties, and the question it answers.
• Run a monthly audit query: events that fired zero times in 30 days, events missing a global property, and near duplicate pairs.
• Publish the short list of what was retired. Silent removal is how trust in the data dies.

Instrument, validate, then document

Instrumentation is code, so it gets the same treatment as code: tested before release, versioned with the repo, and reviewed by someone other than the author.

• Fire each event in staging and confirm the payload matches the schema exactly, including nulls.
• Keep the tracking plan in the repository beside the code it describes. A wiki page drifts; a file that ships with the diff does not.
• A contract test in CI fails the build when an event name or required property is missing.