Telemetry Principles

These principles inform every recommendation in this documentation. They are not abstract theory -- they are hard-won lessons from hundreds of B2B product analytics implementations. When you face a design decision, come back here.

Telemetry is infrastructure

Product telemetry is not a nice-to-have bolted on before launch. It is infrastructure that enables all future analysis, experimentation, and data-driven decisions.

Invest in getting it right early. The cost of fixing bad telemetry compounds over time -- migrating historical data is expensive and error-prone, and living with a seam in your analytics permanently undermines trust in the numbers.

Plan first, implement second

Never add tracking ad-hoc. The process is always:

1. Define the event in the tracking plan
2. Review and approve
3. Implement

The tracking plan is the source of truth. Code should match the plan, not the other way around. When the plan and the code disagree, the code is wrong.

See Naming Conventions for the standards your plan should enforce.

Track behaviors, not metrics

Events capture what users do. Metrics are derived from events later.

• Right: Track Report_Created -- a user performed an action
• Wrong: Track Weekly_Active_Users -- that is a metric, not an event

Design events to answer "what happened?" not "what is the number?" Metrics like activation rate, engagement score, and churn probability are computed downstream from behavioral events.

B2B means two entities

In B2B SaaS, both users and accounts are first-class entities. This is the fundamental difference from B2C analytics.

Every event must be attributable to:

• A user (who did it)
• An account (which organization)

Always call group() to establish account context. Never lose account context on events. Without it, account-level analysis is impossible, and B2B analytics tools like Accoil cannot function.

See B2B Tracking Patterns for implementation details.

Opinionated defaults beat flexibility

Make decisions. Take positions. Consistency matters more than flexibility.

• Pick a naming convention and enforce it
• Pick an event structure and stick to it
• Pick a property schema and standardize

It is better to have a "wrong" consistent standard than no standard. The cost of inconsistency -- fragmented data, queries that miss events, dashboards that undercount -- far exceeds the cost of any single convention choice.

Less is more

Every event has costs:

Track what you need to answer questions, not everything you might need. The cost of adding an event later is trivial. The cost of paying for a useless event for months is not.

See Cost Optimization for strategies to manage these costs.

Properties over events

When in doubt, add a property to an existing event rather than creating a new event.

• Right: Report_Created with a report_type trait set on the account
• Wrong: Standard_Report_Created + Custom_Report_Created + Template_Report_Created

Three events where one would suffice means three times the volume for no additional insight. Use properties and traits for variation; use separate events for fundamentally different actions.

IDs over values

Include IDs in your data, not full values:

• Right: user_id: "usr_123"
• Wrong: user_email: "jane@example.com"

IDs enable joins across systems. Full values create PII risk, storage bloat, and compliance headaches. Store human-readable values as traits via identify and group calls, and reference entities by ID everywhere else.

Outcomes over mechanisms

Track what happened, not how it happened:

• Right: Report_Created
• Wrong: Create_Report_Button_Clicked

If the button changes to a keyboard shortcut, a menu item, or an API call, the outcome-based event still makes sense. The mechanism-based event is coupled to your UI and breaks the moment the UI changes.

Align tracking with business goals

Before choosing what to track, identify the key metrics that align with your business goals. Different goals require different tracking strategies:

Tracking strategy should be goal-driven, not feature-driven. Track what helps you make decisions, not everything that happens.

Future-proof, not future-guess

Track what you need to support any reasonable future analysis, but do not speculate.

Good question: "Could we analyze activation paths with this data?"

Bad question: "What if someday we want to know X?"

Cover the essential event categories -- lifecycle, core value, collaboration, billing -- but do not add events speculatively. Every speculative event is a recurring cost for data nobody uses.

Implementation-aware design

A tracking plan that cannot be implemented is useless. Consider:

• SDK capabilities and limitations
• Performance implications
• Developer experience
• Testability

Design with implementation architecture in mind. If a developer cannot easily instrument an event, the event will not be instrumented correctly.

Validation is cheaper than debugging

Catch tracking issues at implementation time, not when dashboards break.

• Type-safe instrumentation code with centralized event definitions
• Runtime validation in development via debug mode
• Automated tests for critical events
• Monitoring for production event volume changes

Build validation into the workflow. A missed event caught in code review costs minutes. A missed event caught after a quarter of bad data costs trust.

Version and document

Tracking plans change. Products evolve. Treat your tracking plan like a schema -- with migrations.

• Version your tracking plan
• Keep a changelog of additions, changes, and deprecations
• Document breaking changes before they ship
• Plan deprecations with timelines

When the tracking plan is undocumented, new team members cannot understand what is tracked, troubleshooting requires reading source code, and data strategy drifts from business goals without anyone noticing.

Ownership matters

Someone owns the tracking plan. Someone reviews changes. Someone maintains it.

Without ownership:

• Events drift from the plan
• Documentation goes stale
• Quality degrades silently
• Data becomes untrustworthy

Assign ownership to a person or team. Make tracking plan review part of the product development process, not an afterthought.

Start small, iterate

You do not need perfect telemetry on day one.

Start with:

1. Lifecycle events -- signup, activation signals
2. Core value events -- the actions your product exists to enable
3. Billing events -- trials, upgrades, commercial signals

Add more as real questions arise. Ship something correct, then expand. The event categories guide tells you where to focus first.