An instrumentation specification translates approved measurement design into a change that engineering, analytics and product can implement and test.
It is not the permanent definition of the event. That belongs in the event catalogue. The specification should reference that definition, describe what this delivery change must do, and make the conditions for acceptance explicit.
Template
Change title:
[Short description of the instrumentation change]
Change purpose:
[Question, metric or decision this change supports]
Related workflow and step:
[Workflow catalogue item and meaningful step]
Event catalogue reference:
[Approved event name and definition version]
Delivery scope:
[New event / changed event / property change / migration / retirement]
Source of truth and producer:
[System that knows the fact occurred and component that emits the event]
Event schema version:
[Version or compatibility rule]
Fire when:
[Exact successful state or observable condition]
Do not fire when:
- [Attempt that does not reach the condition]
- [Retry or duplicate]
- [Excluded, failed or reversed state]
Required identifiers:
- [identifier: purpose and join rule]
Required properties:
- [property: type, allowed values and purpose]
Optional properties:
- [property: type, allowed values and purpose]
Event time and delivery:
- [Business-event timestamp]
- [Ingestion timestamp]
- [Retry and deduplication rule]
- [Late, replayed and out-of-order handling]
- [Reversal or cancellation handling]
Privacy, access and retention:
- [Data deliberately excluded]
- [Access restrictions]
- [Retention expectation]
- [Required privacy, consent or governance review]
Environments and rollout:
- [Development, test and production expectations]
- [Feature flag or phased rollout]
- [Backfill or migration rule]
- [Old event or schema retirement]
Acceptance criteria:
- [Positive test]
- [Negative test]
- [Duplicate or retry test]
- [Property and schema validation]
- [Join and metric validation]
- [Privacy and access validation]
- [Monitoring or reconciliation check]
Owners and reviewers:
- [Delivery owner]
- [Event-definition steward]
- [Analytics reviewer]
- [Privacy or governance reviewer where required]
Release and review status:
[Draft / approved / implemented / validated / monitoring / complete / superseded]
Known risks and open questions:
[Dependencies, assumptions, failure modes or unresolved decisions]
Example: record a persisted quote acceptance
Change title:
Emit quote.accepted from the quote-state service
Change purpose:
Support the 30-day request acceptance rate and analysis of time from request publication to digital agreement.
Related workflow and step:
Request, compare and accept service quotes — accept a suitable quote
Event catalogue reference:
quote.accepted, approved definition version 2
Delivery scope:
Replace the current client-side acceptance-click event with a server-side event emitted after the acceptance transaction commits.
Source of truth and producer:
The quote-state service owns the persisted quote and request status. It emits the event through the transactional event publisher after a successful state transition.
Event schema version:
quote.accepted v2. Existing consumers of the click event must migrate before the old event is retired.
Fire when:
A valid quote changes from an accept-able state to accepted, the related request state is updated and the transaction commits successfully.
Do not fire when:
- The customer opens the confirmation interface.
- The customer selects accept but validation or persistence fails.
- The client or queue retries an already committed acceptance.
- An administrator views or edits the quote without creating the accepted state.
- A later cancellation occurs; cancellation is recorded separately.
Required identifiers:
- request_id: joins the accepted quote to the eligible customer opportunity
- quote_id: identifies the accepted quote
- provider_account_id: identifies the provider account associated with the quote
- customer_account_id: identifies the customer account where needed for authorised analysis
- acceptance_change_id: stable idempotency and deduplication key for the state transition
Required properties:
- quote_version: integer version accepted by the customer
- service_type: controlled service category
- request_age_days: integer derived from publication and acceptance times
- valid_quote_count: integer count of valid quotes available at acceptance
- workflow_version: controlled marketplace workflow version
Optional properties:
- acceptance_route: comparison, message_thread or quote_detail
- required_site_visit: controlled boolean where the operational definition is available
Event time and delivery:
- event_time is the committed state-change timestamp in UTC
- ingested_at records arrival in the analytics pipeline
- retries retain acceptance_change_id and must not create another analytical fact
- late or replayed records retain event_time and are included according to the metric's late-data rule
- quote.acceptance_cancelled records a later reversal without deleting quote.accepted
Privacy, access and retention:
- Do not include names, addresses, telephone numbers, message text, free-text quote content or detailed service records.
- Limit identifiers to authorised product and analytics roles.
- Apply the documented analytical retention period and deletion process.
- Complete privacy review before production because the event links customer and provider accounts.
Environments and rollout:
- Validate schema and state transitions in development and test environments.
- Run v1 click and v2 state events in parallel for one agreed reconciliation period.
- Do not backfill historical click events as accepted state changes.
- Retire the click event only after downstream consumers and dashboards have migrated.
Acceptance criteria:
- One v2 event appears after a successful first acceptance transition.
- No v2 event appears when the transaction fails or the user cancels before confirmation.
- Repeated API requests with the same acceptance change create one analytical record.
- Required identifiers and properties are present and valid.
- The event joins to the correct eligible request and accepted quote.
- A later cancellation creates the reversal event and preserves the original acceptance.
- No prohibited personal or free-text data appears in the payload.
- Test and production access follows the approved permissions.
- Reconciliation between persisted accepted states and emitted events meets the agreed threshold.
Owners and reviewers:
- Quote-state engineering team: delivery and reliability
- Marketplace product and analytics representatives: definition and metric use
- Data platform representative: schema and delivery review
- Privacy reviewer: identifiers, access and retention
Release and review status:
Approved for implementation
Known risks and open questions:
Confirm the parallel-run period, reconciliation threshold, late-data window and retirement date for the old click event.
Specify the state, not the interface
A delivery ticket that says “track the accept button” is easy to implement and difficult to trust.
The specification should identify the strongest source for the fact being claimed. For a committed outcome, that is usually the service or database transaction that persists the state, not the browser interaction that attempted it.
Interface events can still support usability diagnosis. Keep them separate and name them according to the observed interaction rather than allowing them to impersonate a successful outcome.
Delivery semantics affect metric correctness
Retries, queue re-delivery, late events and reversals are not technical footnotes. They determine whether the resulting metric counts the same fact once, several times or not at all.
The specification should therefore state:
- the idempotency or deduplication key;
- whether one object may legitimately produce several events;
- the business-event timestamp;
- the treatment of ingestion delay and replay;
- the relationship between versions;
- the handling of cancellations and reversals;
- the source used to reconcile completeness.
A metric definition cannot rescue an event stream whose delivery behaviour is unknown.
Acceptance needs negative tests
A positive test proves that an event can appear. It does not prove that it appears only when it should.
Include tests for:
- failed transactions;
- validation blocks;
- abandoned confirmations;
- repeated submissions;
- automatic retries;
- duplicate queue delivery;
- out-of-order records;
- missing or invalid properties;
- unexpected personal data;
- later reversal.
The most important acceptance criteria often describe when nothing should be recorded.
Treat privacy as part of correctness
An implementation is not correct merely because its event count matches expectations.
Instrumentation should also meet the agreed purpose, minimisation, access and retention constraints. Properties without a defined use should not enter the payload. Sensitive context should remain in the operational source unless authorised measurement genuinely requires it.
Close the specification after validation
A specification is delivery-specific. After rollout:
- validate the implementation and downstream metric;
- update the durable event catalogue if the approved definition changed;
- record known limitations or accepted debt;
- retire superseded events, properties and consumers;
- close or mark the specification as superseded.
Do not turn delivery specifications into a second event catalogue. The event catalogue explains what remains true; the specification explains how one change was delivered and accepted.