Instrumentation & Event Dictionary Template

Purpose

This template captures a consistent, discoverable, and maintainable definition for each tracked event and its fields. Use it to ensure instrumentation matches business intent, supports reliable metrics, and prevents common telemetry mistakes such as duplicated events, ambiguous fields, or undocumented transformations.

When to use

• Before adding a new analytics/telemetry event or property.
• When onboarding teams to a shared analytics schema.
• To review existing events for drift, duplication, or missing ownership.

How this template helps

• Makes event intent explicit so downstream analysts and BI tools produce trustworthy metrics.
• Provides a single source of truth for event semantics, owners, and privacy/retention rules.
• Supports automated validation and schema checks when combined with tooling.

Required columns (and how to fill them)

1. Event name (string)

   Canonical, dot-delimited name following your naming convention (example: user.signup.completed or checkout.purchase.completed). Prefer lower_snake or dot.delimited consistently; avoid embedding implementation details.

2. Description (plain language)

   Business meaning and intended analytic use. Explain who cares about the event, what question it answers, and how it differs from similar events.

3. Owner (team/person)

   Primary owner responsible for correctness, schema changes, and consumer communication. Include team name, role, and contact (email or Slack handle).

4. Properties (fields) — schema

   List each property with name, type, allowed values, nullable/required, example value, and short description. Indicate semantic types (e.g., currency, ISO-8601 timestamp, user_id).

5. Version

   Semantic version or integer for the event schema. Use versioning policy (major for breaking changes, minor for additions) and track migration notes.

6. Provenance / Source

   System or service that emits the event (e.g., web-client-v2, payments-service). Helps trace back to the emitting code for debugging.

7. Trusted source (boolean)

   Is this event considered a canonical record for the underlying business fact? If false, indicate why and where a trusted source exists.

8. Transformation notes

   Any downstream ETL, normalization, enrichment, or aggregation steps applied to the event or its fields (e.g., "user_id anonymized for PII, currency converted to USD").

9. Upstream systems / dependencies

   Other systems or events that feed this event or that this event depends on (helpful for lineage).

10. Retention

    How long raw and aggregated data are stored (e.g., 365 days raw, 5 years aggregated). Include archival rules.

11. Privacy flags / compliance

    Indicate PII/PHI presence, GDPR/CCPA considerations, masking required, user consent dependencies, and any opt-out behavior.

12. Validation rules and SLAs

    List automatic checks (presence, type checks, allowed value constraints, cardinality, reasonable ranges) and expected data freshness / SLA for event arrival and pipeline processing.

13. Example entry(s)

    Provide at least one realistic JSON-like example of the emitted event with values for properties.

14. Change log / last updated

    Record schema changes, why they were made, who approved them, and the date.

Naming conventions — practical rules

• Use consistent separators (dot, underscore). Pick one and stick to it.
• Start names with a domain or product area: checkout., user., system.
• Prefer verbs for events that represent actions (e.g., user.login.success), nouns for records (e.g., order.recorded).
• Avoid embedding environment or implementation detail (e.g., don’t include "v1" unless it’s part of deliberate schema versioning).

Example event definitions

Validation checklist (for each new or changed event)

1. Does the description explain the analytic question this event answers?
2. Is there a clear owner and an acceptance process for changes?
3. Are property names and types specified with examples?
4. Are privacy, retention, and compliance requirements recorded?
5. Are automated validation rules defined for type, cardinality, and reasonable ranges?
6. Is the trusted source boolean set correctly, and is lineage documented?
7. Is at least one concrete example payload included?

Maintenance & governance — keep this dictionary the source of truth

• Designate a schema steward role (per product area) responsible for approvals and breaking-change communication.
• Require a short review period and changelog entry before making breaking changes.
• Automate schema checks in CI where possible (type checks, required fields, allowed values).
• Publish a lightweight change policy: how to deprecate, how long consumers have to migrate, and how version bumps are signaled.
• Schedule periodic audits to find duplicate events, unused events, or inconsistent property naming.

Common pitfalls and how to avoid them

• Ad-hoc naming by different teams — mitigate with templates, linters, and onboarding docs.
• Too many optional properties that obscure required signals — prefer focused required fields and a separate enrichment pipeline for optional data.
• Coupling analytic semantics to implementation details — keep names and semantics stable even if implementation changes.
• Missing ownership — require an owner before an event is accepted into production.

Next steps and optional enhancements

Start by copying this template into your shared schema registry or a central spreadsheet. For faster adoption consider these capability enhancements (implementation notes below):

• Render this template as an interactive form to create and validate entries (captures structured schema fields and example payloads).
• Connect entries to automated CI checks and a schema registry so breaking changes fail builds unless approved.
• Expose the dictionary as a versioned API so analytics tools can read canonical schemas programmatically.

Quick governance checklist (one-page)

1. Owner assigned and reachable.
2. Business description clearly written.
3. Properties documented with types and examples.
4. Privacy & retention set.
5. Validation rules defined.
6. Example payload included.
7. Change log updated.

Use this template as the foundation for a living event dictionary. Preserve the examples and the validation checklist as your schema and tooling mature.