Tracking Agent docs

The Tracking Agent Google Sheet: tabs, notes and requests

The Google Sheet is a read-only view of your tracking plan, rebuilt from the registry after every merge to your default branch. On the plan tabs, two columns belong to people, Verified in <tool> and Analyst Notes, and every rebuild keeps them. Anyone can ask for new tracking on the Requests tab, and the agent turns each request into a proposal pull request.

On the plan tabs, Verified in <tool> (named for your analytics tool, such as Verified in Mixpanel) and Analyst Notes. On the Audit tab, Verified and Fix (below). A person marks an item verified after seeing its data arrive with the right properties; nothing else sets it, because "verified" isn't a registry status.

Each rebuild reads those two columns first and writes them back to the same row, keyed by event and property, however the rows move. If a row goes away because a property was removed or an event deprecated, its note moves to the Deprecated tab as an orphaned note, with the date, rather than being lost. Everything else on the plan tabs is rewritten by the sync.

The playbook chapter on event verification covers what to check before marking an event verified.

Every column except Verified and Fix is protected. Each rebuild keeps those two columns, and every watch row, matched by Source, Item and Type. A ticked Fix is picked up by the hourly requests job, which opens one fix pull request per area; the audit says how fixes go through review.

1. Anyone with access writes a row: what they need in plain words, such as "which coupon was used at checkout", and who they are. They leave the status empty.
2. Every hour, the agent picks up new rows a few at a time (5 per run by default, set by requests.max_per_run in .datalyze/config.yaml) and marks each one Processing before it starts. Rows past the limit wait for the next run.
3. For each row it proposes tracking changes against the registry and the code, checked the same way as any pull request's proposal, opens a pull request with the proposal, and writes the pull request link and status back to the row.
4. The PR check takes that proposal over as it stands only if it carries a valid signature from the runner and the pull request has no other changes. Once anyone else pushes to it, the pull request is analysed like any other.
5. The request goes through normal review: a person approves, the agent implements and verifies, a person signs off. The row's status follows along until it merges.

If the agent can't tell what's needed, the row's status says it needs more detail, with a question in the note. Add the detail, clear the status, and it goes round again. A row marked Failed says what went wrong in the note; clear the status to try again.

With the Datalyze template: no Google Cloud project

1. Make the Sheet from the Datalyze template. It adds a Datalyze menu.
2. Use the menu to connect it. That creates the tabs and a token.
3. Deploy the template's script as an Apps Script web app, running as you.
4. Paste the web app's URL and the token into setup. They become the repo secrets DATALYZE_SHEET_URL and DATALYZE_SHEET_TOKEN.

The script answers only requests that carry the token, and runs as you, so it can reach only this Sheet.

With a Google service account

1. In a Google Cloud project, enable the Google Sheets API and create a service account with a JSON key.
2. Share the Sheet with the service account's email as an editor.
3. Save the whole JSON key as the repo secret GOOGLE_SERVICE_ACCOUNT_JSON.
4. Set sheet.mode: service_account and sheet.spreadsheet_id in .datalyze/config.yaml. The ID is the part of the Sheet's URL after /spreadsheets/d/.

After every merge to your default branch, datalyze sync-sheet rebuilds it from the registry on that branch. A failed sync never blocks a pull request or a merge: it's tried once more in the same run, and if that fails too, only that workflow run fails and the Sheet stays as it was until the next merge. To rebuild it by hand, open Actions, then Datalyze, then Run workflow, and pick sync-sheet.