Tracking Agent docs

The tracking plan method behind the Tracking Agent

Every change the Tracking Agent proposes follows four design rules, prefers no change over a new event, and never renames an event in place. The rules: an event exists because someone asks a question it answers; intent and outcome come as a pair; one action from many places is one event; success and failure live on one event. Your _conventions.yaml changes the naming, not these rules.

Each new event carries its question in the question field. If nobody can state the question, the event doesn't get added. The playbook chapter on creating a tracking plan explains the reasoning behind each rule, and Mixpanel's guide to events and properties describes the event-plus-property model the rules build on.

Track these

• Sign-up, login and onboarding steps: one event per step type with a step property, not one per screen.
• The first value moment for each product, with is_first_<thing> on the outcome event.
• Core actions that create, change, use or export the product's value.
• State changes such as a plan upgraded or a subscription paused.
• Money: every payment, plan and credit outcome, sent from the server, with status.
• Search and filters only where they're central, with char_count and result_count, never the query.
• Server outcomes with no user present: scheduled jobs, background processing, webhooks. These are the events most often missed.

Ignore these

• Hovers, scrolls, tooltips, collapsing panels, theme toggles and dismissed banners.
• Pagination, and tab switches inside one screen unless the tabs are different features.
• Screen views that carry no decision, and marketing-site navigation other than calls to action into sign-up.
• Settings tweaks with no product consequence, and anything per keystroke.

The test: would a PM or analyst filter, break down or count by this in a report? Yes means track it. Maybe means skip it and raise a question: adding an event later costs one pull request, and removing one costs a migration.

For each behaviour a change touches, the agent picks the first outcome that fits, in this order:

1. No tracking change. Refactors, copy, styling, or anything that fails rule 1, with the reason in one line.
2. Extend an existing event. A new way in gets a new entry_point value; a new variant gets a new enum value. This is the most common correct outcome for a UI change.
3. Modify an existing event. Its firing moment, properties or values change, under the breaking-change protocol below.
4. Deprecate an existing event. The surface or action is gone: status: deprecated, a deprecated_reason, and replaced_by if something replaces it.
5. Add a new event. Only when none of the above fits.

More than 5 new events in one pull request (budget.new_events_per_pr in _conventions.yaml), or more than 2 for one new screen, needs a written reason for each event. Plans rot one reasonable-looking event at a time.

Breaking an existing event is worse than missing a new one. A missing event costs a week of data; a silently changed one corrupts every dashboard built on it. So every item that changes the meaning of past data is labelled breaking and follows this protocol:

1. Never rename in place. Add the new event and mark the old one deprecated with deprecated_reason and replaced_by. The old entry stays, because it explains the history in your analytics tool.
2. Send both for one release for core events (sign-up, login, money, first-value events and anything on a dashboard), with dual_fire_until on the old entry, so reports can move without a gap.
3. Log a changed firing moment with a changelog line starting SEMANTICS: and the date, so an analyst who sees a step change in a chart can find the cause.
4. Give a changed type a new property name. Analytics tools can't retype history.
5. Flag it in the report's breaking changes section, with the dashboards or funnels likely affected.

To find breaks, the agent walks a checklist for every event and user property a change can reach: firing moment moved, surface removed or merged, a new way into the same action, a new step in a flow, an enum value changed, a type or unit changed, a property's source changed, an error path changed, identity or account context changed, and a rename in code.

Raw user text, prompts, search queries, file names, transcripts, emails or phone numbers as event properties, API secrets, and card or bank details. Send lengths (char_count), buckets (file_size_bucket) or IDs instead. datalyze validate flags property names that look like personal data, using pii_patterns in _conventions.yaml.