Instrumenting your SaaS product: from raw events to a clean telemetry spec

# Instrumenting your SaaS product: from raw events to a clean telemetry spec

A team ships a slick new "bulk export" feature on a Thursday. By Monday, the PM wants to know: did anyone use it? The answer is a shrug. There was no tracking. The feature exists, but it is invisible in the data. Nobody can say if it drove retention, wasted engineering time, or quietly broke.

This happens constantly. Instrumentation (the practice of adding code that records what users do) gets treated as an afterthought. The result is a product that flies blind.

This lesson shows how to design a telemetry spec (a documented plan for what events you capture and what each one means) so that activation, feature adoption, and account context are all measurable, without collecting so much noise that the data becomes useless.

Why "just track everything" fails

The instinct is to log every click. It backfires.

• Noise buries signal. If you have 4,000 event types and half are named button_click, no one can find the ten events that actually matter.
• Cost scales with volume. Analytics platforms and data warehouses bill on event volume and storage. Untamed tracking gets expensive fast.
• Inconsistency kills trust. When signup_complete means three different things depending on which engineer wrote it, every dashboard becomes an argument.

Good instrumentation is a design problem, not a volume problem. You decide, up front, the small set of things worth measuring and how you will name them forever.

The three layers every SaaS event needs

Think of each event as answering three questions: who, what, and in what context.

1. Activation: did the user reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → first value?

Activation is the moment a new user experiences the product's core value for the first time. It is not signup. For a project management tool, activation might be "created first project and invited a teammate." For an analytics product, it might be "connected a data source and viewed a chart."

Pick one clear activation event per product. Everything else measures the path toward it.

2. Feature adoption: is the feature being used, by whom, how often?

Adoption tracks whether shipped features get real use. You want to distinguish:

• Breadth: how many accounts use the feature at all.
• Depth: how often each active user uses it.

That "bulk export" feature needs a single, well-named event fired when the export actually completes, not just when the button is clicked.

3. Account context: which company, which plan, which segment?

SaaS is usually sold to accounts (organizations), not individuals. A user action is far more valuable when you know the account behind it: the plan tier, seat count, industry, and whether they are in trial. This is account-level context, and it turns "someone exported data" into "an enterprise trial account on day 3 exported data," which is a retention signal worth acting on.

Designing the event taxonomy

A taxonomy is your naming system: the rules that make every event predictable.

Use a consistent naming convention

Pick one pattern and never deviate. A widely used convention is Object + Action in past tense:

• Project Created
• Export Completed
• Invite Sent
• Subscription Upgraded

Avoid vague verbs (clicked, viewed on everything) and avoid encoding data into the name. Do not create Export Completed CSV and Export Completed PDF as separate events. The format is a property, not a new event.

Separate events from properties

An event is the thing that happened. Properties are the details about it.

• Event: Export Completed
• Properties: format: "csv", row_count: 4200, duration_ms: 830

This keeps your event list short and your analysis flexible. You can later filter Export Completed by format without inventing new event names.

Segment's tracking plan best practices guide is a solid free reference for these conventions.

Standardize your identifiers

Every event should carry:

• user_id: a stable identifier that never changes (not the email, which can change).
• account_id: the organization the user belongs to.
• timestamp: when it happened, in UTC.

Consistent IDs are what let you join user behavior to account context in your warehouse later.

Writing the tracking plan

The tracking plan is a living document (usually a spreadsheet or a schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → file) that lists every approved event, its properties, types, and a plain-English description. It is the contract between product, engineering, and data.

A minimal row looks like this:

| Event | Description | Property | Type | Required |

|-------|-------------|----------|------|----------|

| Export Completed | Fires when a data export finishes successfully | format | string | yes |

| | | row_count | integer | yes |

| | | duration_ms | integer | no |

Before any engineer writes tracking code, the event must exist in this plan. That single rule prevents most instrumentation chaos.

Versioning: because your product will change

Your product evolves, so your events will too. Versioning means managing changes to events without silently breaking old data.

The cardinal rule: never redefine an existing event. If the meaning of Export Completed changes, you have corrupted your history. Instead:

• Add new properties (safe, backward compatible).
• Deprecate old events with a clear end date rather than deleting them.
• If a breaking change is unavoidable, create a new versioned event and document the cutover.

Here is a compact JSON schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → fragment showing an event definition with a version field:

{
  "event": "Export Completed",
  "version": 2,
  "properties": {
    "format":    { "type": "string", "enum": ["csv", "pdf", "xlsx"] },
    "row_count": { "type": "integer" },
    "duration_ms": { "type": "integer" }
  },
  "required": ["format", "row_count"]
}

Storing definitions like this lets you validate incoming events automatically and reject anything that does not match the spec. That validation is how you keep noise out at the source.

🎬 [VIDEO: "How to Build a Tracking Plan" - youtube.com - a practical walkthrough of designing events, properties, and naming conventions for product analytics]

Governance: who owns the spec

A telemetry spec without an owner rots within a quarter. Assign clear responsibility:

• Product proposes new events tied to a feature or a question they need answered.
• Data or analytics engineering reviews for naming, duplication, and schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → fit.
• Engineering implements only approved events.

Add a lightweight review step: no new event ships without one approval. This is not bureaucracy, it is the difference between 40 trustworthy events and 4,000 useless ones.

A worked example: instrumenting a trial funnelfunnelThe customer journey from awareness to purchase, typically Awareness, Interest, Consideration, Decision, Action, with prospects narrowing at each stage.View full definition →

Imagine a B2B SaaS with a 14 day free trial. You want to know why trials convert or churn. Here is a tight event set, not a sprawling one:

1. Trial Started (property: plan_tier)

2. Data Source Connected (this is your activation event)

3. Report Created

4. Report Shared (a strong depth signal: sharing means the tool has organizational value)

5. Invite Sent

6. Subscription Upgraded (conversion)

Six events. Each carries user_id, account_id, timestamp, and relevant properties. With account context joined in, you can now answer real questions:

• What percentage of trial accounts hit activation within 48 hours?
• Do accounts that fire Report Shared convert at a higher rate?
• Which plan tier has the weakest activation?

Notice what is missing: no page_viewed on every screen, no button_hovered. Those add volume and cost while answering nothing. You can always add an event later. You cannot easily recover from a polluted event stream.

Privacy is part of the spec

Instrumentation touches personal data, so it falls under privacy regulations such as the GDPR (the European Union's General Data Protection Regulation, which governs how personal data is collected and used) and similar frameworks elsewhere. Two practical rules:

• Do not put personal data in event properties unless you truly need it and have a lawful basis. Avoid logging raw email addresses, full names, or free-text fields that might contain sensitive content.
• Respect consent. If a user has not consented to analytics tracking, your instrumentation should not fire. Bake this into the spec, not into a scramble later.

This is general guidance, not legal advice. Confirm your obligations with your own counsel.

Key Takeaways

• Design before you track. Decide the small set of events that answer real business questions, then instrument only those. "Track everything" produces noise, cost, and distrust.
• Every event has three layers: activation (did they reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → first value), adoption (breadth and depth of feature use), and account context (which organization, plan, and segment).
• Standardize naming and separate events from properties. Use Object + Action past tense, keep event names generic, and push details into properties so your event list stays short and analysis stays flexible.
• Maintain a versioned tracking plan as a living contract. Never redefine an existing event, add properties rather than break them, and require one review before any new event ships.
• Build privacy in from the start. Keep personal data out of properties and respect consent at the point of collection, not as an afterthought.