Writing instrumentation requirements

Instrumentation requirements translate measurement design into something engineering and analytics can implement, test, and maintain.

They should explain more than an event name. A reliable requirement defines the behaviour, source of truth, firing rule, identifiers, properties, exclusions, privacy constraints, and evidence needed to accept the implementation.

Without those decisions, an event may exist in the analytics tool while still being unsuitable for the metric it was meant to support.

Start from the evidence need

Begin with the question and workflow, not the tracking syntax.

For the service-quotes workflow, the team may need to answer:

What proportion of eligible service requests result in a recorded quote acceptance within 30 days?

That question establishes several requirements before anyone writes an event name:

• the primary unit is the eligible service request;
• acceptance must be linked to a request and a specific quote;
• the accepted state needs an authoritative source;
• repeated clicks or retries must not create repeated acceptances;
• acceptance is a digital completion point, not proof of completed work;
• the implementation must support a cohort window based on request publication.

The event is one part of that measurement design.

Requirement anatomy

A strong requirement normally includes:

Question and decision use
Related workflow and step
Event name and description
Actor and measurement unit
Authoritative source of truth
Fire condition
Do not fire conditions
Identifiers and join keys
Required properties
Allowed values and null behaviour
Deduplication or idempotency rule
Ordering, latency, and replay expectations
Privacy, consent, retention, and access constraints
Related metric definitions
Acceptance and monitoring criteria
Owner and review trigger

Not every event needs a long document. The detail should match the risk of getting it wrong.

Example: quote.accepted

Purpose

Provide evidence that a customer selected a specific submitted quote for an eligible service request through the product.

Fire when

The authoritative quote record changes from an eligible non-accepted state to accepted, and the change is successfully persisted.

Do not fire when

• the customer opens an acceptance confirmation screen but does not confirm;
• a client request is sent but the server rejects or rolls back the change;
• the accepted record is re-read or replayed without a new state transition;
• an administrator views or edits unrelated quote details;
• a provider marks work as scheduled or completed;
• an off-platform agreement is reported without an accepted quote record, unless a separately defined reporting event exists.

Actor and units

The actor is normally the customer or authorised customer representative. The event must identify the service request and accepted quote so analysis can retain the correct request-level and quote-level units.

Required identifiers

service_request_id
quote_id
provider_id
customer_account_id or another approved pseudonymous actor key

The identifiers should support joins without placing names, email addresses, telephone numbers, postal addresses, or message text into the analytics event.

Useful properties

acceptance_route
quote_version
service_category
request_route
workflow_version
provider_availability_band

Only collect a property when it supports an identified metric, dimension, quality check, or operational need. “It might be useful later” is not a sufficient purpose.

Choose the authoritative source

The most visible interface action is not always the best event source.

For quote.accepted, a button click proves only that someone attempted to accept. The persisted state change is stronger evidence that the product recorded the acceptance successfully.

Possible sources include:

Choose the source that best represents the behaviour the metric claims to measure. Record weaker attempt events separately when they support diagnosis.

Design for duplicates, retries, and late data

Real systems retry requests, replay messages, backfill history, and process events out of order.

The requirement should state:

• whether the event may occur more than once for the same state transition;
• which event or transition identifier supports deduplication;
• how quote acceptance changes or reversals are represented;
• which timestamp reflects the business occurrence and which reflects ingestion;
• whether backfilled events are distinguishable from live activity;
• how late arrivals affect cohort metrics and dashboard freshness.

For an acceptance event, “fires once” is not enough. It should mean once per accepted state transition, with a stable identifier that allows downstream systems to remove accidental duplicates.

Properties need contracts

A property name without an allowed-value rule simply moves ambiguity into the data.

For each required property, define:

• type and format;
• allowed values or reference source;
• whether null is permitted;
• what null means;
• which system owns the value;
• whether the value describes the moment of the event or can change later.

For example, service_category should not alternate between internal codes, public labels, free text, and historic values without a documented rule.

Privacy and minimisation are part of the requirement

Instrumentation should collect the minimum data necessary for the stated question.

For the quotes workflow, avoid sending:

• free-text customer requirements;
• message bodies;
• names and direct contact details;
• precise property or service addresses where a broader region is sufficient;
• sensitive service details;
• full quote documents or attachments.

Use approved identifiers and controlled categories instead. Document who can access the data, how long it is retained, and whether consent, privacy, security, or governance review is required.

Hashing or pseudonymising an identifier does not remove every privacy risk. Combinations of category, geography, timestamp, and account data can still become identifying.

Acceptance criteria should test meaning, not only delivery

A tracking ticket is not complete because an event appears once in a debugger.

Acceptance criteria for quote.accepted might include:

• the event fires after the accepted state is persisted;
• it does not fire for an unconfirmed click or failed request;
• retries do not create duplicate accepted transitions;
• request, quote, provider, and approved actor identifiers are present and valid;
• required properties use the agreed types and values;
• excluded personal or free-text data is absent;
• timestamps reflect the agreed occurrence and ingestion rules;
• reversal or cancellation behaviour matches the specification;
• the event can be joined to the eligible request cohort;
• test, staging, and production data are distinguishable;
• the event is visible in monitoring with expected latency;
• a sample metric calculation produces the expected request-level result.

Include negative tests. A requirement is clearer when it states when the event must not fire.

Separate durable definitions from change specifications

The event catalogue should hold the current durable meaning of quote.accepted.

An instrumentation specification should describe the implementation or change being delivered: new source, property addition, migration, validation plan, release date, and rollback or monitoring expectations.

Once the change is live and validated, update the durable catalogue. Do not leave the only correct definition buried in a closed delivery ticket.

Review after implementation

Instrumentation needs operational follow-through.

Review it when:

• the workflow or source system changes;
• event volume changes unexpectedly;
• null or unknown property values increase;
• duplicates, ordering problems, or latency appear;
• the event is used for a materially different decision;
• privacy or retention expectations change;
• the related metric loses trust.

Instrumentation is not reliable because it was specified carefully once. It becomes reliable when the intended meaning survives implementation, release, and later product change.