Most telemetry starts casually. Add an event. Track a click. Log a payload. Send a metric. Build the dashboard later.
That works until the product grows.
At scale, telemetry becomes an interface between product, engineering, analytics, support, security, and operations. If the event names drift, fields change silently, or cardinality explodes, the data stops being trustworthy.
Telemetry needs contracts.
Name The Behavior, Not The Implementation
Good events describe stable product behavior.
checkout_submitted is more durable than button_clicked_v2. file_upload_failed is more useful than xhr_error. The name should survive UI redesigns and internal refactors.
The contract should define what the event means, when it fires, and when it must not fire.
Control The Fields
Telemetry fields need schemas.
Define required fields, optional fields, allowed values, units, timestamps, release identifiers, and privacy classification. Avoid sending arbitrary objects because they are convenient in the moment.
Structured events are easier to query, cheaper to store, and safer to share.
Watch Cardinality
High-cardinality fields can make observability systems expensive or unusable.
User IDs, URLs, raw error messages, device names, and generated strings need careful treatment. Sometimes they belong in logs, not metrics. Sometimes they need hashing, sampling, or aggregation.
The contract should say where detail belongs.
Version The Contract
Telemetry evolves.
Version schemas, test event output, and review changes like API changes. If dashboards, alerts, or reports depend on an event, breaking it should be visible before deployment.
Good telemetry is not accidental exhaust. It is product infrastructure.