An event analytics taxonomy for product teams is a contract about what happened, not a decorative list of click names. When a customer creates a workspace, invites a colleague or completes an export, the event should preserve the same business meaning across web, mobile, backend jobs and the warehouse. Without that contract, dashboards disagree, experiments use incompatible populations and analysts spend more time interpreting instrumentation than answering product questions.
The best starting point is a decision, such as whether onboarding helps an account reach its first useful outcome. Work backward to the observable state changes, then define events and properties that can answer the question. This guide complements data contracts between systems and teams and finance reporting automation, where trustworthy downstream reporting depends on stable upstream meaning.
Start with decisions and business facts
Separate an event from a screen interaction. project_created describes a durable business fact; create_button_clicked describes an interface action that may move, duplicate or fail. Interface events are useful for diagnosing usability, but outcome metrics should normally use confirmed state changes from the authoritative system. Define the trigger precisely: after validation, after a committed database transaction, or after an external provider confirms success. That choice determines whether retries and abandoned attempts inflate the result.
A tracking plan should name the question, event owner, producing application, trigger, schema, identity requirements, consent basis and expected destination. Snowplow's current tracking-design guidance similarly treats plans as containers for event specifications and reusable entity structures. Product, engineering and analytics should approve the meaning together. Approval does not imply permanence; it establishes a controlled way to evolve a fact without silently changing historical interpretation.
| Question | Preferred event | Essential context | Common mistake |
|---|---|---|---|
| Did an account activate? | workspace_activated | workspaceid, plan, activationpath, occurred_at | Using a page view as activation |
| Did an invitation succeed? | member_invited | workspaceid, inviterrole, channel, result | Firing only on button click |
| Was value delivered? | reportexportcompleted | reporttype, format, rowcount, duration_ms | Combining start and completion |
| Why did setup fail? | integrationconnectionfailed | provider, stage, error_class, retryable | Sending unrestricted error text |
Choose event and property naming rules
Use one grammatical pattern, usually object plus completed action in snake_case: invoice_sent, workspace_created, subscription_cancelled. Past tense signals that the recorded fact occurred; teams may choose another convention if it is applied consistently. Avoid names tied to page layout, campaign labels or a vendor's current interface. Google Analytics names are case-sensitive, start with a letter and accept letters, numbers and underscores, so a lowercase convention also prevents accidental duplicates such as Sign_Up and sign_up.
Properties should answer reusable dimensions of who, what, where, when and how without restating the event name. Use stable identifiers rather than display names, bounded enumerations rather than free text, and explicit units such as duration_ms or amount_minor_units. Keep personal or sensitive data out unless there is a documented purpose and control. Namespace shared technical attributes where that reduces collisions; OpenTelemetry's conventions demonstrate how namespaces can preserve meaning across signals and implementations.
Make every event a versioned schema contract
Document each property with a type, definition, allowed values, null policy, example and source. Mark which values are required at collection time and which are enriched later. Include event identity, event time, ingestion time, producer version and an anonymous or authenticated actor identifier where appropriate. The contract should distinguish a missing value from an inapplicable value; converting both to an empty string destroys useful quality signals.
Treat schema evolution like an API change. Adding an optional property is usually compatible. Renaming a required property, changing its unit or reinterpreting an enum can break models and historical comparisons. For an incompatible change, publish a new schema version, support a migration window and update consumers deliberately. Do not mutate old rows to imitate a new definition unless the backfill method, coverage and limitations are recorded.
| Contract field | Example | Validation rule | Owner |
|---|---|---|---|
| Event trigger | Committed workspace record | Exactly once per successful workspace | Product engineering |
| Identity | workspace_id UUID | Present and syntactically valid | Platform |
| Enum | activation_path | self_serve, assisted, import | Product analytics |
| Time | occurred_at UTC | Producer time within accepted skew | Data platform |
| Version | schema_version 2 | Supported version registry | Data governance |
Resolve identity, time and duplicate delivery
Identity design should reflect the analysis grain. A person may use several devices, belong to multiple workspaces and act under different roles. Preserve separate anonymous_id, user_id and workspace_id concepts rather than overwriting one with another. Define when anonymous history may be linked after authentication and how deletion requests propagate. For B2B products, account-level activation is not the same as user-level engagement; attach both only when the relationship existed at event time.
Event pipelines are commonly at-least-once, so give important events a stable event_id and deduplicate within a documented boundary. Preserve occurred_at from the producer and received_at from ingestion; late mobile uploads and queued jobs make the distinction material. Decide how funnels handle late events, clock skew and reordered steps. A dashboard that changes after late arrival is not inherently wrong, but its freshness and restatement policy must be visible.
Implement the taxonomy through the release workflow
- Write the product question, decision owner and baseline before proposing events.
- Map confirmed business states and diagnostic interactions across client and server.
- Draft event specifications with triggers, examples, schemas and privacy classification.
- Review names and reusable properties with product, engineering, analytics and data owners.
- Generate or share typed constants where practical, then instrument the authoritative trigger.
- Validate payloads in development, test expected counts in staging and inspect real samples.
- Release behind a bounded rollout, reconcile against source records and certify the event for analysis.
- Monitor volume, completeness and cardinality; deprecate through a recorded migration window.
Automate what can be proved mechanically. CI can reject unknown event names, invalid schemas and prohibited property patterns. A staging test can assert that one completed workflow emits one expected event. Production checks can compare event counts with authoritative records and alert on sudden null, enum or cardinality changes. Human review remains necessary for meaning: a payload may satisfy JSON Schema while still representing the wrong business moment.
Operate taxonomy quality as a product
Maintain a searchable registry showing current, proposed, deprecated and trusted events. Amplitude's official designation is one product example of distinguishing reviewed events from everything merely ingested. The platform feature is less important than the operating rule: an owner confirms definition, data quality and intended use before an event supports a decision. Archive noisy auto-capture and test events from normal discovery without pretending that hiding them repairs upstream collection.
Review a small scorecard monthly: percentage of critical events with owners, required-property completeness, unexplained volume variance, duplicate rate, late-arrival rate, undocumented values and time to approve a schema change. Google Analytics publishes event and parameter limits, but staying below a vendor limit is only a floor. High-cardinality values, uncontrolled URLs and free-form errors can remain expensive or unusable well before a hard limit is reached.
Example: model a SaaS onboarding funnel
Suppose a small-business SaaS product wants to improve activation. Define workspace_created when the workspace transaction commits, data_source_connected after validated credentials produce a successful test, first_report_published after a report becomes accessible, and workspace_activated when the agreed activation rule is satisfied. Keep connection_attempted and connection_failed as diagnostics. The funnel now measures business progress while failure events explain where intervention is needed.
Use a semantic metric such as activated workspaces divided by eligible workspaces within fourteen days. Version the eligibility and activation definitions beside the event schemas. Segment by acquisition path or plan using governed properties, not new event names. If the business changes activation from one published report to two collaborating members, create a new metric version and retain the old series long enough to explain the transition. The CRM automation control guide applies the same principle to operational handoffs.
Before approving a tracking change, ask an analyst who did not author it to answer the original product question from sample payloads. If that person cannot identify the population, trigger, unit and exclusions, the contract is not ready. This short interpretation test catches semantic ambiguity that schema validators cannot see and gives the owner a concrete revision target.
Key takeaways
- Model durable business facts separately from interface diagnostics.
- Use one readable naming grammar and bounded, reusable properties.
- Version event schemas and preserve historical meaning through migrations.
- Design identity, event time and deduplication before building funnels.
- Certify events only after semantic review and production reconciliation.
Frequently asked questions
Should events use noun-verb or verb-noun names?
Either can work. Choose one form that makes completed facts unambiguous, document tense and casing, and enforce it. Consistency and precise triggers matter more than copying a vendor example. Check destination-specific reserved names and length rules before adopting the convention.
Can auto-capture replace a tracking plan?
Auto-capture is useful for exploratory interface analysis, but selectors and labels change and do not necessarily prove an outcome. Keep it as a diagnostic layer. Instrument important business states explicitly from the most authoritative producer and validate them against system records.
How should a team rename a bad production event?
Publish the replacement definition, instrument both during a bounded transition, update downstream models and dashboards, compare counts, then deprecate the old name with an owner and date. Avoid silently rewriting the event in a destination because other consumers may still receive the original payload.
Conclusion
A useful event analytics taxonomy is a maintained interface between product behavior and decisions. Define facts from authoritative state, constrain names and properties, version schemas, test delivery and certify only reconciled data. With ownership and change control in place, the taxonomy can evolve without turning every product release into a new dialect of the customer journey.