The key takeaway
Start with a product decision, define the events needed to inform it, and document exactly when each event fires. Use stable identities, distinguish attempts from outcomes, and review data quality with each relevant release. Collect only the properties needed for the question being answered.
Begin with a decision
Write the question in plain language: where do new workspaces stop before completing their first report? Then identify the decisions the answer could change, such as simplifying imports or clarifying validation errors.
A metric without an associated decision can grow into a dashboard nobody owns. Start with a small set of questions and nominate someone to review the results. Expand instrumentation when a concrete gap appears.
Define events as a contract
For each event, document its name, trigger, responsible system and properties. Specify whether it represents an attempt, acceptance or completed outcome. A browser click on “Create report” is different from a report being ready to view.
| Event | Meaning | Example property |
|---|---|---|
| report_requested | A valid request was accepted | source_type |
| report_completed | Processing produced a usable report | duration_bucket |
| report_failed | Processing ended without a usable result | failure_category |
Keep names tied to domain actions rather than screen positions. “Primary button clicked” becomes ambiguous when the layout changes. Record units and allowed values for properties so teams do not mix seconds with milliseconds or invent incompatible categories.
Handle identity and duplicates deliberately
Decide whether a metric counts people, workspaces or operations. Team products often need an account-level view because several users contribute to the same outcome. Document how anonymous activity is associated with signed-in activity, if that association is needed at all.
Use a stable operation identifier where retries could create duplicate events. Keep operational recovery separate from new customer demand: replaying a failed background task should not look like another purchase or another activated workspace.
Limit collection to useful properties
Prefer structured categories over free-text fields. Avoid putting document contents, access tokens or personal messages into analytics payloads. Review collection against the product's privacy choices and the purpose of each event.
Make test and internal activity identifiable so it can be excluded from customer reporting. Sample onboarding data should also be distinguishable from work completed with a customer's own information.
Verify meaning after releases
Test the event sequence for success, failure, retries and cancellation. Compare a small set of observed operations with the analytics records, then inspect unusual shifts after rollout. A sudden increase in completion may be an instrumentation change.
Use the events to evaluate onboarding outcomes and guide the next step in your MVP roadmap. Keep the definitions alongside the product so later teams can explain what historical numbers actually counted.