Writing instrumentation requirements

Instrumentation requirements explain what behaviour the product should capture, when events should fire, and what context needs to be included.

They translate measurement design into something engineers can implement and analysts can trust.

Good instrumentation requirements do not start with a list of events. They start with the workflow, the product question, and the decisions the measurement should support.

Requirement anatomy

A strong instrumentation requirement should include:

Product question
Related workflow
Workflow step
Event name
Behaviour captured
Fire condition
Do not fire condition
Required properties
Related metrics
Acceptance criteria
Owner or reviewer

This anatomy turns measurement design into something that can be implemented, tested, reviewed, and maintained.

Why instrumentation requirements matter

Weak instrumentation creates weak measurement.

If events are missing, duplicated, vague, or fired at the wrong moment, the metrics built from them become harder to trust. If properties are missing, the team may know that something happened but not enough about where, why, or to whom.

Clear requirements help teams agree:

• what behaviour should be captured
• which workflow step each event relates to
• when the event should fire
• which properties are required
• which metrics will use the event
• how the event should be tested

This reduces ambiguity between product, design, engineering, and analytics.

Start with the measurement purpose

Before writing event requirements, define the question the measurement should answer.

For account registration, the question might be:

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

That question points to a workflow:

View registration form
↓
Enter details
↓
Submit form
↓
Verify email
↓
Access product

It also points to the evidence the team needs. The team may need to know whether users view the form, submit it, encounter errors, verify their email, and reach the product.

Instrumentation requirements should make that evidence explicit.

Define events from workflow steps

Each event should relate to a meaningful point in the workflow.

For registration, the requirements might include:

Workflow step                  Event

View registration form          registration.form_viewed
Submit form                     registration.form_submitted
Validation error shown          registration.form_error_shown
Verify email                    registration.email_verified
Access product                  registration.completed

The workflow step describes the behaviour. The event records that the behaviour happened.

This keeps instrumentation connected to product measurement rather than interface details alone.

Specify when each event fires

An event name is not enough. The requirement should state exactly when the event should fire.

For example:

Event:
registration.form_submitted

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.

This prevents different people from interpreting the event differently.

Timing is especially important for completion events. registration.completed could mean form submitted, account created, email verified, or first product access. The requirement should remove that ambiguity.

Define required properties

Properties add context to an event.

For example:

Event:
registration.form_error_shown

Required properties:
error_type
field_name
entry_point
device_type
workflow_version

These properties help the team understand what kind of error appeared, where it happened, and which users or contexts were affected.

Properties should be included because they support interpretation, segmentation, or metric definitions. Avoid adding properties simply because they might be available.

Connect events to metrics

Instrumentation requirements should show how each event will be used.

For registration, events might support metrics such as:

• form submission rate
• form error rate
• email verification rate
• registration completion rate
• time to complete registration
• drop-off between form submission and email verification

This helps engineers understand why the event matters and helps analysts check whether the implementation will support the intended metric.

If an event does not support a useful question, metric, or decision, it may not need to be included.

Include acceptance criteria

Instrumentation requirements should be testable.

For each event, define what must be true for the implementation to be accepted.

For example:

• the event fires once per valid form submission
• the event does not fire when validation blocks submission
• required properties are present
• property values match the agreed format
• the event appears in the analytics tool or data layer
• the event can be joined to the relevant user or session identifier
• the event has been tested in the expected environments

Acceptance criteria turn instrumentation from a vague tracking request into a delivery requirement.

A simple instrumentation requirement

A lightweight requirement might look like this:

Workflow:
Register for an account

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

Workflow step:
Submit registration form

Event:
registration.form_submitted

Purpose:
Show that the user submitted the registration form.

Fire when:
The user submits the 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
device_type
workflow_version

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

Acceptance criteria:
Event fires once per valid submission.
Required properties are present.
Event can be tested in the analytics environment.

This is enough to align product, engineering, and analytics before implementation.

Common mistakes

Common instrumentation problems include:

• requesting events without explaining the workflow
• naming events before defining the behaviour
• failing to specify when events should fire
• missing required properties
• tracking low-level clicks without a measurement purpose
• treating instrumentation as an engineering-only task
• failing to test events before using them in metrics
• not updating requirements when the workflow changes

These mistakes create measurement debt. The product may appear to be tracked, but the evidence becomes harder to interpret and maintain.

How to apply this

When writing instrumentation requirements, include:

• the product question
• the workflow and step
• the event name
• the behaviour being captured
• the fire condition
• any conditions where the event should not fire
• required properties
• related metrics
• acceptance criteria
• owner or reviewer

Start with the most important workflow events. Capture enough evidence to support decisions, but avoid turning instrumentation into a record of every possible interaction.

Related articles

• Instrumentation specification template
• Event catalogue template
• Event naming convention examples

Key takeaway

Instrumentation requirements turn measurement design into implementable tracking.

Good requirements connect workflow steps, events, properties, metrics, and acceptance criteria. They help teams capture reliable evidence without losing sight of the product question the measurement is meant to answer.