Skip to main content

Event Taxonomies and Tracking Plans

An event taxonomy is a controlled vocabulary; a tracking plan is the operational contract that says exactly when each event is emitted, which properties it carries, who owns it, and why it may be collected. Names alone are insufficient: two teams can emit signup_complete at different points and silently combine unlike facts.

Prerequisites​

Complete users, sessions, events, and business entities. Understand JSON objects and primitive types.

Learning goals​

  • Define low-cardinality event names around completed occurrences.
  • Separate occurrence time from receipt time.
  • Validate required properties and consent purpose at ingestion.
  • Evolve a tracking plan with explicit schema compatibility.

Anatomy of a tracking plan​

The repository contract fixes schema version 1, UTC, an owner, an effective time, an identity snapshot, and five event definitions. Every definition contains:

  • a stable event name such as account_created;
  • a trigger precise enough for two implementations to agree;
  • required property names and types;
  • an allowed collection purpose.

OpenTelemetry's event guidance provides a useful general boundary: an event is a named point-in-time occurrence; dynamic values belong in attributes, not in the event name; occurrence and observation timestamps are distinct. Product events are application-specific, so this fixture does not pretend its names are OpenTelemetry standard names.

Prefer past-tense outcomes (account_created) when the fact is a completed transition. Commands (create_account_clicked) may still be useful, but they answer an intent or interface question. Do not encode identifiers into names such as exported_report_8472; use a validated property.

Schema changes​

Adding an optional property can be backward compatible if consumers tolerate absence. Changing a required property's type, trigger, units, or meaning is not. Create a new semantic version, preserve old decoding, migrate producers, and publish the metric impact. A schema version without a migration policy is only a label.

Consent is checked before analytical use, not treated as another segmentation property. The fixture deliberately contains one page_view delivered for product_measurement with analytics consent denied. It remains in this educational raw fixture so validation can prove it is rejected; a production collector should prevent or tightly quarantine that boundary violation.

Worked example​

import json
from pathlib import Path

root = Path("tests/fixtures/product-analytics")
plan = json.loads((root / "tracking-plan-v1.json").read_text())
rows = [json.loads(line) for line in (root / "events-v1.jsonl").read_text().splitlines()]
unique = {}
for row in rows:
unique.setdefault(row["event_id"], row)
types = {"string": str, "boolean": bool}
def valid(row):
required = plan["events"][row["event_name"]]["required_properties"]
return all(key in row["properties"] and isinstance(row["properties"][key], types[kind])
for key, kind in required.items())
invalid = [row for row in unique.values() if not valid(row)]
boundary = [row for row in unique.values()
if row["purpose"] == "product_measurement" and not row["analytics_consent"]]
print(f"schema_version={plan['schema_version']} allowed_events={len(plan['events'])} valid_rows={len(unique) - len(invalid)}")
print(f"duplicate_rows={len(rows) - len(unique)} invalid_rows={len(invalid)} consent_boundary_rows={len(boundary)}")

Expected output:

schema_version=1 allowed_events=5 valid_rows=13
duplicate_rows=1 invalid_rows=1 consent_boundary_rows=1

Validation makes the malformed integer feature observable instead of coercing it to a string and hiding producer drift.

Limitations and common mistakes​

  • A syntactically valid event can still fire at the wrong business moment.
  • Automatically coercing types hides producer defects and can merge distinct categories.
  • High-cardinality or sensitive properties increase cost and privacy risk without guaranteeing decision value.
  • Reusing a name after changing its meaning corrupts longitudinal comparisons.
  • Client clocks may be wrong; preserve both occurrence and receipt time and define how each is used.

Practice​

Propose version 2 of feature_used with a required outcome. Decide whether it is compatible, how old producers are handled, and which metrics must be reviewed. Include purpose and retention decisions.

Next steps​

Turn validated events into complete, reviewable definitions in metric definitions and semantic contracts.

Primary sources​

Checked 2026-10-19: OpenTelemetry Semantic Conventions 1.44.0, events and naming; W3C, Privacy Principles: Purpose Limitation.