Event Tracking

For a long time a product team held exactly two numbers: how many people signed up, and how much money came in. Everything between those two was blank. What a new user clicked first, which screen they abandoned, how many people actually opened the feature that shipped last week — none of it was written down anywhere.

So meetings stalled in the same spot every time. Someone would ask whether people were using the sharing feature that launched last month, and the answer was that it felt like it had picked up a bit. Digging through server logs didn't help, because those logs recorded which address received a request, not which human meant to share a document. There was no way to separate a person pressing the share button from a person reloading the page. The decision ended up going to whoever spoke with the most confidence.

Event tracking fills that blank at the moment it opens. Instead of reconstructing behavior afterward, the product writes a line the instant the button is pressed: this person, at this time, did this thing. The record moves from analysis time to action time.

A single line holds a timestamp, a person, an action, and a few fields describing that action. Where a server log says a request hit an address and finished in 40 milliseconds, an event says that at 2:13 p.m. this person shared one folder by link. You can't fix a product with the first line. You can with the second.

The word "event" is doing real work in that sentence. It marks a thing that happened at a point in time and is finished, as opposed to a state that is simply true right now. States can be read whenever you feel like asking — a database can tell you today how many documents exist. Events can't, because the moment has passed. That difference is the reason this whole field exists as a separate discipline instead of a query someone writes on a Tuesday.

The defining property of this work is that it doesn't reach backward. To know how many people pressed share last month, the line had to already be recording last month. Instrument it today and the data starts today. Wonder in April about the first month of a feature shipped in March and that answer never arrives. That is why instrumentation stopped being something an analyst catches up on later and became something decided while the feature is being specified — and why a planning document and a naming rulebook grew up around it into a field of their own.

The ten terms under event tracking fall into five groups. What separates them is the order in which a single line of record gets made and finds its place: what the line itself is (units), what gets agreed before anything is instrumented (design), where the line is sent from (methods), whose behavior the line belongs to (identity), and what goes missing along the way (risk).

Units describe the shape of the record. There are three.

1. Event — one line describing one action. Something like: on March 4th at 2:13 p.m., user A shared a document. Nothing can be counted or split until these lines exist.
2. Event property — the extra fields attached to that line. Knowing a document was shared doesn't tell you whether a link was copied or an email invite was sent, so fields like sharing method and document type ride along. An event without properties can only answer how often something happened, never in which cases it happens more.
3. User property — a value attached to the person rather than the action: plan, signup date, company size. Timing is what separates it from an event property. An event property describes what was true at that instant and never changes afterward, while a user property describes the present state, so moving from free to paid overwrites it.

Design is the group that settles the agreement before anything gets instrumented. There are two.

4. Tracking plan — the document listing which actions get recorded, under which names, with which properties. Without it each engineer invents a name on the spot for the feature they happen to be building, and six months later nobody in the company can say what a given name counts.
5. Naming convention — the rule for how those names are formed. If the same action lands as doc_shared on the web, shareDocument in the app, and Document Shared in the extension, the share count splits three ways and none of the three shows the whole picture. The rule usually fits in a few lines: lowercase and underscores, object before action, past tense throughout.

Methods separate where the line is sent from. There are two.

6. Client-side tracking — sent straight from the user's browser or app. It can capture things that only ever happen on screen, like hovering over a button and moving on without clicking. In exchange, ad blockers and dropped connections keep some of it from ever arriving.
7. Server-side tracking — recorded by the server that handled the request. Anything with money attached, like whether a payment was actually approved, belongs here: it can't be blocked and the user can't edit the values. What it can't see is any movement that never reaches the server. In practice teams don't pick one. Money-related facts go out from the server, screen-only behavior goes out from the client.

Identity is the group that ties scattered lines to one person. There are two.

8. User identifier — the unique value used to connect lines left by the same person. After login it's the account id; before login it's a temporary value stored on the device.
9. Identity resolution — the processing that stitches those two values together. Someone who clicks an ad, browses for twenty minutes, and then signs up leaves those twenty minutes under one value and everything afterward under another. Leave them apart and one new customer is counted as an anonymous visitor plus a separate new member, and the ad that produced the signup can't be traced.

Risk covers what leaks out of the pipe.

10. Data loss — events that never arrive, because of blocking or errors. The awkward part isn't that the count shrinks but that it doesn't shrink evenly. If the people running blockers cluster in one segment, that segment alone fades out of the picture you're making decisions from.

The five groups sit in a chain. Design settles the names, methods split where lines are sent, units decide what rides along, identity groups them by person, and risk tells you how much to discount what you read. Who owns that chain varies. With several data people around, a dedicated owner maintains the tracking plan; at fifteen people, the person who specified the feature usually specifies its instrumentation too. Either way engineers do the instrumenting, so the agreement has to be finished before the build starts. Retrofitting it afterward costs a release of its own, and the weeks in between stay empty forever.

Reading the chain backward is also the fastest way to debug a number that looks wrong. A share count that halved overnight is far more often a renamed event, a release that dropped the instrumentation, or a new blocker version than an actual collapse in sharing. Checking the record before questioning the behavior saves most of the argument.

The step teams skip most often is the first one. Instrument the urgent feature now and clean up the names later, and by the time later comes the accumulated records carry the old names — renaming them severs the past from the present.

"Is that button instrumented? If we add it now, numbers start next week."

No record means no way to recover the past, and instrumenting today only fills forward.

"That one's client-side, so it's probably running about 20 percent under."

Some of it was blocked or dropped, so read the trend rather than trusting the absolute figure.

"Web and app use different names, so you have to add the two together."

The same action was instrumented under two event names and the count is split.

At Pagedeck the spec template for a new feature ends with a section for what gets recorded, and it is filled in before anyone opens a code editor. During the week the document templates feature was being written up, Mia put two lines in that section: opened the template list, created a document from a template. Theo asked why they had to be separate lines, and Mia said she needed the share of people who open the list and leave without picking anything, because that ratio decides what else belongs in the list. Which template was chosen became a property, and the names followed the house rule of lowercase and underscores.

Three weeks later the numbers came back wrong. Documents created on the web were there; documents created in the app were missing entirely, because the app engineer had instrumented the same action under a different name. The three missing weeks couldn't be recovered, so the app share for that month stayed blank for good. After that, the recording section became something both engineers sign off on before the build starts.

The most common assumption is that the data can be pulled whenever it's needed. Logs pile up on the server the whole time the service runs, so it feels like everything is already stored somewhere and only extraction is left. Those logs record which request arrived and how many milliseconds it took to serve — a technical trace, not a record of what a person was trying to do. Most companies also keep them for only thirty or ninety days because of volume. Leave it there, and every quarterly review that calls for a comparison against last quarter hits a missing left-hand number, and the meeting ends by deciding to start collecting today.

Instrumenting everything, just in case, goes wrong just as often. It's hard to argue against, since regret runs the other way. But once three hundred events exist as names nobody opens, a new analyst trying to count shares has five similar names and no way to tell which one still arrives correctly. Two people then answer the same question with two different events and bring two different numbers to the meeting. The moment the numbers split, the meeting stops deciding anything and starts arbitrating. Starting small and adding on demand tends to last longer, and a short list stays cheap to maintain: every event is a name somebody has to keep accurate through redesigns, renames, and platform rewrites. One test makes the choice easy: if you can't write a sentence naming the decision this record would change, the event isn't ready to be instrumented. A list grown on the hope of eventual usefulness is the first thing that has to be torn out later.