Events are the product's diary

Actor is who did it. In GitHub's diary it is an account with a numeric id and a login; the login can be renamed, the id cannot. In the one hour we opened, 7 accounts appear under more than one login. Anything that counts people must count the id.

Action and object are the verb and the noun. GitHub folds them into one type (PushEvent, WatchEvent, CreateEvent) plus a detail in the payload: a CreateEvent can create a branch, a tag or a whole repository, and only the payload says which. That is the first product-analytics trap you will meet: one name hiding three different moments.

Time is a UTC timestamp. Properties are everything else that travels with the event: how many commits a push carried, which branch a pull request targets. Properties are where the useful questions live, and they are also what gets forgotten when an event is added in a hurry.

A users table says what is true now: plan, country, signup date. An event stream says what happened, in order. Every product metric that involves time, activation, engagement, adoption, retention, is a question about the order of things, so it can only be answered from events. The users table is still needed, to say who a person is; the events say what they did. Session 2 of the analyst track loads a real hour of the stream and shows how different it looks from a table: most actors appear once, a few appear thousands of times.

Segment's guidance, which most tools and teams have converged on, is to pick objects first (Product, Application, Repository) and then the actions a customer performs on them (Viewed, Installed, Created), so that an event reads "Product Viewed". Their house style is Proper Case for event names and snake_case for properties, and they are explicit that the style matters less than the consistency: "The only thing that really matters is that you keep it consistent!"

Three rules follow. Past tense, because an event records something that happened. No variables in the name: "Plan Upgraded" with a property plan = "pro", never "Upgraded To Pro", or every new plan becomes a new event nobody remembers to add to the chart. One moment, one name: if two names might mean the same thing, one of them is a bug.

A tracking plan is a table: event name, the moment that triggers it, the properties it must carry with their types, and an owner. It looks like documentation and works like a contract. Engineers implement against it, analysts query against it, and a validator can check the live stream against it. Run against the real hour, the five-line plan above finds zero type violations, and still catches 234 "Code Pushed" events with commits = 0: valid by type, wrong by meaning. That is the kind of thing only a written plan lets you notice, because only a written plan says what a push is supposed to mean.

GitHub's own CreateEvent is the cautionary example. In the hour we opened, 39,497 CreateEvents are split 27,168 branches, 10,384 repositories and 1,945 tags. A chart titled "Creates per hour" would be 69 percent branches and read as if it counted new projects. The payload knows the difference; the name does not. When you inherit a diary, the first job is to find the names that hide more than one moment and split them in the plan.

The tempting shortcut, when a data source has no signup event, is to call the first time an account appears in your window its start. On GitHub that is almost always wrong: most accounts active in any given hour have existed for years and were simply quiet before the window opened. A "new users" chart built that way counts people who took a holiday.

What the public diary does record is the birth of a repository: a CreateEvent whose payload says repository happens exactly once, at the moment it is created. In our hour, 10,384 public repositories were born. That is why the activation bench in analyst session 8 treats a new repository the way a SaaS product treats a new workspace, and why it says so on the widget.

Every tracking plan should carry a short section called "what we do not see": logged-out browsing, activity inside an integration, offline use, consent opt-outs, anything behind an ad blocker. It costs five lines and it prevents the most common executive misreading, which is treating the absence of an event as the absence of the behaviour. A product review that asks "is this a real drop, or a drop in what we can see?" is only possible if someone wrote the blanks down.