How to Spec a Product Instrumentation Plan

Jameson Pitts
Managing Director
October 28, 2021

How to Spec a Product Instrumentation Plan

One of the first tasks in rolling out a growth marketing and product analytics tech stack is to develop an instrumentation plan. This is an opportunity for the various teams at your organization to agree on what user data and events should be collected in order evaluate your marketing and product’s performance.

Oftentimes we see product and development teams instrumenting events on the fly, which leads to messy and incomplete data. And without documentation on what each event means, it can be easy to make mistakes in interpreting the data or using that instrumentation to fire user messaging at the wrong time. Even if corrected, your data becomes difficult to analyze historically since the event itself or its naming has changed.

In short, measure twice and cut once. Read on for our approach to planning instrumentation in a rigorous and scalable way.

What is Product Instrumentation Anyway?

Lacking instrumentation is the biggest technology stack mistake we see our growth stage clients making. So what is instrumentation?

It refers to the process of implementing tracking tools and systems to measure marketing funnels, product usage, and organize your customer data. Think instruments, as in the dashboard of gauges of an airplane cockpit — all the tools and sensors that report on the plane’s performance and location.

In modern product instrumentation, the best practice is to use a single Customer Data Platform, like Segment, to instrument your product. This allows you to only instrument once, for all of the tools in your tech stack.

This is an image of Segment's tree.
Segment's Data Tree

Segment will then connect to all your other tools — your CRM, ad attribution, Google Analytics, or product analytics — and send the same stream of data to each. This is a huge time saver over telling each individual analytics or marketing app what data to collect.

This also means that lots of care is needed in outlining a tracking plan for Segment, since this user data will power all of your analytics across the organization. (Remember, measure twice.)

Types of Data That Segment Tracks

The most important types of data needed to plan how to track are user attributes, web and app page views, and user events.

In Segment lingo, these correspond to four different API calls:

  • Identify (who is the customer?)
  • Page (what web page are they on?)
  • Screen (what app screen are they on?)
  • Track (what are they doing?)

We’ve found the best way to begin your instrumentation plan is by creating a document with sections for these 4 types of calls, and breaking down what needs to be collected for each. This document will be your customer data and instrumentation north star for product and marketing teams!

Don’t wing it. Start with an Existing Spec

If lacking instrumentation is the biggest tech mistake made by startups, the biggest and most common mistake we see within instrumentation is basically winging it. It can be tempting to implement a tool like Segment, and then just go ham making up events for all the things you want to track.

There are two reasons as to why this is a bad idea:

First off, this problem has already been solved. You don’t need to reinvent it, but are better served learning from other’s mistakes and using existing best practices.

Second, while a big part of Segment’s value is the technical tubes that connect your tools, an even bigger part is the work they have put into standardizing how each tool reads and writes customer data. This means, if you use an existing spec, your other tools will know out of the box how to interpret the data generated by that spec.

Let’s break it down by each call. For Identify, start by populating the reserved traits that Segment have already defined and resist the temptation to invent your own user attributes. Continue that with Page and Screen.

The most important choice is of a Track spec. Segment has complete standardized tracking plans for user lifecycle events for Mobile, Ecommerce, Email, Video, and more. Most often we rely on the Native Mobile and Ecommerce specs. There’s huge value in having all of the basic transactional events defined in a way that all of your product analytics and marketing tools will be able to interpret out of the box.

Continue your instrumentation plan by copying in these reserved traits for each type of call, and all of the relevant pre-defined events from your closest fit tracking plan. The basic principle is to over-collect data. Any of the reserved events might be useful in analyzing performance or triggering marketing events.

Supplement with Custom Attributes and Events

The last step is to move back through each API call and enrich them with any attributes or events that are specific to your application.

It’s important to only create new attributes or events if Segment has not already reserved them. For example, be careful not to make a phoneNumber attribute when phone already exists as a reserved trait in the Identify spec. However, maybe your app is a marketplace with different types of users that need to be identified with a role attribute that doesn’t exist.

For Track events, think about your user lifecycle from beginning to end. What are all of the key actions that are meaningful to your business and the performance of your UI, and of those which are not already covered by an existing spec like Ecommerce? A common example is user onboarding: likely you have many custom steps in your onboarding process that are critical for measuring drop-off. Create those custom events, but be careful to match naming conventions and to reuse reserved attributes to keep your data neat.

That’s it! You’ll be left with a document that contains all of the data you collect on each user, and can be implemented using Segment’s API. This is our approach, but the truth is that any form of planning and documentation is a huge step toward a professionalized product marketing program.



1204 San Antonio St
Second Floor
Austin, TX 78701
This is an image of a orange square button.