Product Metrics and Analytics Playbook
Toolkit

Instrumentation specification template

An instrumentation specification describes how measurement should be implemented in the product.

It translates product questions, workflows, events, properties, and metrics into clear requirements that engineering and analytics teams can build, test, and maintain.

The specification is not just a list of event names. It should explain what behaviour needs to be captured, when each event should fire, what context is required, and how the event will be used.

What this is

This is a copyable template for turning measurement design into implementation detail. Use it when tracking needs to be built, changed, tested, or reviewed.

Acceptance criteria are the most important part. Without them, tracking can look implemented but still fail to produce trustworthy evidence.

When to use it

Use an instrumentation specification when a team is adding, changing, or reviewing product tracking.

It is useful when teams need to:

  • implement new workflow events
  • update tracking after a product change
  • define event fire conditions
  • specify required properties
  • connect events to metrics
  • test whether tracking works as expected
  • reduce ambiguity between product, engineering, and analytics

A specification is especially useful before a release, when instrumentation needs to be treated as part of delivery rather than added afterwards.

What an instrumentation specification should include

A useful specification should give enough detail for teams to understand and test the tracking.

At minimum, include:

  • product question
  • related workflow
  • workflow step
  • event name
  • event description
  • fire condition
  • conditions where the event should not fire
  • required properties
  • related metrics
  • acceptance criteria
  • owner or reviewer
  • implementation status

These fields help the team connect implementation details back to the measurement purpose.

Template

Product question:
[What question this tracking helps answer]

Related workflow:
[Workflow name]

Workflow step:
[Meaningful step the event relates to]

Event name:
[event.name]

Event description:
[Plain-language description of what happened]

Purpose:
[Why this event is needed]

Fire when:
[Exact condition that should trigger the event]

Do not fire when:
[Conditions where the event should not be captured]

Required properties:
- [property_name]: [description and expected values]
- [property_name]: [description and expected values]

Optional properties:
- [property_name]: [description and expected values]

Related metrics:
- [Metric name]
- [Metric name]

Acceptance criteria:
- [How the event should be tested]
- [What must be true for the implementation to be accepted]

Owner or reviewer:
[Person, role, or team]

Implementation status:
[Not started / planned / implemented / tested / needs review / retired]

Notes:
[Any useful context, assumptions, dependencies, or known issues]

The format can be adapted for a ticket, spreadsheet, product requirements document, analytics workspace, or documentation site. The important thing is that the specification is clear enough to implement and test.

Example: registration form submitted

Product question:
Are users able to create an account and access the product without unnecessary friction?

Related workflow:
Register for an account

Workflow step:
Submit form

Event name:
registration.form_submitted

Event description:
The user submitted the registration form.

Purpose:
Show that the user attempted to submit their registration details.

Fire when:
The user submits the registration form and the submission request is sent.

Do not fire when:
The user clicks submit but client-side validation prevents submission.

Required properties:
- entry_point: where the user started registration
- device_type: device category used by the user
- workflow_version: version of the registration workflow

Optional properties:
- organisation_id: organisation associated with the user, where applicable

Related metrics:
- Form submission rate
- Drop-off before email verification
- Time to complete registration

Acceptance criteria:
- Event fires once per valid submission attempt.
- Event does not fire when client-side validation blocks submission.
- Required properties are present.
- Property values match agreed formats.
- Event appears in the analytics environment.
- Event can be associated with the relevant user or session identifier.

Owner or reviewer:
Account access product team and analytics reviewer

Implementation status:
Planned

Notes:
This event captures submission attempt, not successful account creation.

This example keeps the event connected to the workflow, metric logic, and testing criteria.

How to use the template

Start with the product question and workflow before defining the event.

Then work through the specification in this order:

  • define the workflow step
  • name the event
  • describe the behaviour being captured
  • specify when the event should and should not fire
  • list required properties
  • connect the event to metrics
  • define acceptance criteria
  • assign an owner or reviewer

This order helps prevent teams from naming events before they have agreed what behaviour needs to be captured.

Common mistakes

Common mistakes include:

  • starting with event names before defining the workflow
  • omitting fire conditions
  • failing to say when an event should not fire
  • adding properties without explaining how they will be used
  • missing acceptance criteria
  • treating tracking as complete before it has been tested
  • failing to update the specification when the product changes
  • leaving ownership unclear

These mistakes make events harder to trust and metrics harder to explain.

How to maintain it

An instrumentation specification should be updated when the workflow, event, properties, or related metrics change.

Review the specification when:

  • a workflow step is redesigned
  • an event changes meaning
  • a property is added, removed, or renamed
  • a related metric becomes important
  • a dashboard depends on the event
  • confidence in the tracking drops
  • implementation differs from the original requirement

The specification should not become a one-off delivery document. It should remain part of the measurement system’s operating record.

  • Writing instrumentation requirements
  • What makes a good event?
  • Event naming convention examples

Key takeaway

An instrumentation specification turns measurement design into testable implementation detail.

It connects product questions, workflow steps, events, properties, metrics, and acceptance criteria so teams can capture reliable evidence and maintain confidence in the measurement system.