Telemetry Event Contract Review
Overview
Treat telemetry as a versioned producer-consumer contract so analytics changes remain compatible, privacy-aware, and testable.
When to use
Use for new events, renamed properties, type changes, required-field changes, client/server instrumentation, analytics migrations, and dashboard dependency reviews.
When NOT to use
Do not use to transmit live events, query production player data, deploy collectors, or approve privacy-sensitive collection without the responsible human reviewers.
Required inputs and context discovery
Collect baseline and proposed schemas, event IDs and names, property types and optionality, versions, producers, consumers, sampling, timestamps, identity fields, privacy classification, retention, consent rules, rollout, and deprecation window.
Safety and risk level
Read-only contract review. Unknown privacy classification, ambiguous identifiers, missing consent rules, or inaccessible consumer inventories are BLOCKED for approval.
Workflow
- Normalize event IDs, names, versions, properties, types, and optionality.
Completion criterion: duplicate IDs and ambiguous aliases are explicit failures.
- Compare baseline and proposal for additive, breaking, and semantic changes.
Completion criterion: every change has compatibility classification and affected versions.
- Trace producers, consumers, dashboards, experiments, and retention dependencies.
Completion criterion: unknown consumers are
BLOCKED rather than assumed safe.
- Review privacy classification, minimization, consent, sampling, and retention.
Completion criterion: sensitive or unnecessary properties have an owner and disposition.
- Define rollout, dual-write or migration, validation, and deprecation evidence.
Completion criterion: backward compatibility and rollback are testable before deployment.
Evidence and output contract
Produce telemetry-contract-review.json with normalized schemas, compatibility findings, producer-consumer impacts, privacy findings, rollout plan, validation cases, verdict, and limitations.
Handoff contract
Record schema owners, affected producers and consumers, breaking changes, privacy decisions, rollout order, dashboard updates, deprecation deadline, and unresolved gaps.
Pitfalls and anti-rationalization
- Renaming a property is a breaking change for existing consumers.
- Same type does not guarantee same semantics or units.
- Optional client fields may become effectively required downstream.
- Do not collect identifiers merely because storage exists.
Verification checklist
References and scripts
Use the bundled scripts/telemetry_contract.py for deterministic schema compatibility checks. Live collectors and production datasets remain outside this read-only skill.
1---2name: telemetry-event-contract-review3description: Use when reviewing game analytics or telemetry event names, IDs, required properties, types, versions, privacy classes, producers, consumers, and backward compatibility before instrumentation changes.4license: MIT5---6# Telemetry Event Contract Review78## Overview9Treat telemetry as a versioned producer-consumer contract so analytics changes remain compatible, privacy-aware, and testable.1011## When to use12Use for new events, renamed properties, type changes, required-field changes, client/server instrumentation, analytics migrations, and dashboard dependency reviews.1314## When NOT to use15Do not use to transmit live events, query production player data, deploy collectors, or approve privacy-sensitive collection without the responsible human reviewers.1617## Required inputs and context discovery18Collect baseline and proposed schemas, event IDs and names, property types and optionality, versions, producers, consumers, sampling, timestamps, identity fields, privacy classification, retention, consent rules, rollout, and deprecation window.1920## Safety and risk level21Read-only contract review. Unknown privacy classification, ambiguous identifiers, missing consent rules, or inaccessible consumer inventories are `BLOCKED` for approval.2223## Workflow241. Normalize event IDs, names, versions, properties, types, and optionality.25 Completion criterion: duplicate IDs and ambiguous aliases are explicit failures.262. Compare baseline and proposal for additive, breaking, and semantic changes.27 Completion criterion: every change has compatibility classification and affected versions.283. Trace producers, consumers, dashboards, experiments, and retention dependencies.29 Completion criterion: unknown consumers are `BLOCKED` rather than assumed safe.304. Review privacy classification, minimization, consent, sampling, and retention.31 Completion criterion: sensitive or unnecessary properties have an owner and disposition.325. Define rollout, dual-write or migration, validation, and deprecation evidence.33 Completion criterion: backward compatibility and rollback are testable before deployment.3435## Evidence and output contract36Produce `telemetry-contract-review.json` with normalized schemas, compatibility findings, producer-consumer impacts, privacy findings, rollout plan, validation cases, verdict, and limitations.3738## Handoff contract39Record schema owners, affected producers and consumers, breaking changes, privacy decisions, rollout order, dashboard updates, deprecation deadline, and unresolved gaps.4041## Pitfalls and anti-rationalization42- Renaming a property is a breaking change for existing consumers.43- Same type does not guarantee same semantics or units.44- Optional client fields may become effectively required downstream.45- Do not collect identifiers merely because storage exists.4647## Verification checklist48- [ ] IDs and names are unique and versioned.49- [ ] Types, units, and optionality are explicit.50- [ ] Producers and consumers are traced.51- [ ] Privacy and retention are reviewed.52- [ ] Rollout and rollback are testable.5354## References and scripts55Use the bundled [scripts/telemetry_contract.py](scripts/telemetry_contract.py) for deterministic schema compatibility checks. Live collectors and production datasets remain outside this read-only skill.
hoatv2211