Tracking Agent docs

Tracking Agent concepts: registry, typed tracker and proposals

The registry is your tracking plan as YAML files in your repo, and every other Tracking Agent concept checks it, changes it or is generated from it. The typed tracker is generated from it, proposals change it through reviewed pull requests, and conventions, decisions, the baseline and statuses shape how it's judged.

The registry is your tracking plan, kept as YAML files in analytics/registry/. It's the source of truth: every change to it goes through a reviewed pull request, and the Google Sheet is only a view of it. Events are split into one file per area of the product, so teams rarely edit the same file.

analytics/registry/
  _conventions.yaml       the rules: naming, allowed values, budget, typed tracker, scan settings, reviewers
  _properties.yaml        shared event-property vocabulary and banned synonyms
  _user_properties.yaml   user (profile) properties
  _super_properties.yaml  properties sent on every event
  _groups.yaml            group or company properties (optional, B2B)
  _identity.yaml          when identify, alias and reset happen
  _baseline.json          problems accepted at install
  <area>.yaml             events for one area: account.yaml, posts.yaml, billing.yaml
analytics/generated/      the typed tracker (never edited by hand)
analytics/adapter/        the vendor adapter, the only code allowed to call the analytics SDK

The reference lists every field of an event and user property entry, and the playbook chapter on creating a tracking plan explains what a good entry answers.

The typed tracker is a module that datalyze generate writes from the registry into analytics/generated/. Your code calls it instead of the analytics SDK, so a wrong event name, a missing property or a value outside the plan is a compile error.

import { track, serverTrack, user, serverUser } from '@/analytics/generated';

track.publishClicked({ entry_point: 'editor' });                // client events
serverTrack.postCreated(userId, { post_id, entry_point, status: 'success', failure_reason: null });
user.identify(userId);                                           // at sign-up and login
serverUser.setOnce(userId, { signup_date: new Date() });         // user properties set on the server
user.reset();                                                    // at logout

The vendor sits behind an adapter, so changing analytics tool means swapping one file. The generator writes TypeScript, Swift, Kotlin or Dart, and datalyze adapter <vendor> writes the adapter for Mixpanel, PostHog, Amplitude, Segment, RudderStack or GA4 in that language. In capture mode (DATALYZE_CAPTURE=1) the tracker records every call instead of sending it, which is what the generated tests check.

A proposal is the agent's list of tracking changes for one pull request, saved as .datalyze/proposals/pr-<n>.yaml on the pull request's branch. Each item says what changes and why, the question it answers, the evidence (a file and line, or a query and its result), whether it's breaking, and how confident the agent is.

Reviewers edit each item's final copy and its note, which the agent treats as a binding instruction. Decisions come only from /datalyze comments, never from the file. See reviewing.

Conventions are your house rules, in two files. analytics/registry/_conventions.yaml holds the rules a script enforces: the event-name pattern, allowed values, the new-event budget and the reviewers. .datalyze/conventions.md holds rules reviewers made in plain words while reviewing, which the agent treats as binding.

Decisions are the agent's memory of what you said no to. .datalyze/decisions.yaml records rejected items and skips, with reasons, so the agent doesn't propose the same thing again and the next audit can see every skip.

The baseline, _baseline.json, lists the problems accepted at install, so pull requests are judged only on what they add. When the Tracking Agent was installed on this site, the baseline accepted 41 legacy findings, mostly Title Case event names and placement used where the conventions say entry_point.

Regenerate it with datalyze baseline once clean-up pull requests have merged. It changes the rules for everyone, so make your analytics owner its code owner, along with _conventions.yaml and _properties.yaml.

"Verified" is not a status. It's a column in the Google Sheet that a person fills in after seeing the data arrive with the right properties.