Telemetry
Browse docs
Discussion TopicsUpdated July 27, 2026Reviewed by the Telemetry product team2 min read

Use this doc with your coding agent

Copy a Telemetry prompt and ask Claude Code, Codex, or Cursor to instrument the workflow covered here.

PromptsGet API key
On this page
  1. Name the outcome
  2. Choose fields from questions
  3. Plan for change
  4. Review checklist

Designing an Event Schema

An event schema is a contract between the code that emits data and every query, dashboard, alert, or export that consumes it. A small amount of design before instrumentation prevents months of ambiguous data.

Name the outcome

Use a stable noun and past-tense outcome such as api_request_completed, job_failed, or subscription_renewed. Avoid UI wording that changes frequently. When success and failure share the same useful fields, one event with a controlled status value is often easier to compare than separate tables.

Choose fields from questions

For each planned question, identify the operation:

  • Filters need fields such as environment, feature, route, or status.
  • Groups need controlled dimensions such as model, release, or error type.
  • Calculations need typed measurements with explicit units.
  • Investigations need safe identifiers that connect related events.

Record latency_ms, not latency. Store numeric values as numbers and booleans as booleans. Use UTC timestamps. Prefer route_template over a raw URL and error_type over an unbounded exception message.

Document whether an identifier represents a person, account, request, or job. If a field may contain sensitive data, omit it or transform it before the event is created.

Plan for change

Additive changes are usually safest: a query can tolerate a new nullable field. Renaming a field or changing its type can break every consumer. When semantics change materially, add an event_version, write queries that handle the migration window, and remove the old shape only after consumers move.

Keep a representative success, failure, retry, and timeout sample for validation. Run the important SQL before releasing an instrumentation change. A schema is complete only when the values produced by real branches match its documented meaning.

Review checklist

Ask whether the event has a clear owner, a bounded set of status values, explicit units, safe identifiers, and a retention need. Confirm that at least one real query uses each field. Remove values included merely because they are available.

See schema evolution, redacting sensitive data, and the SQL recipes for complete event-contract examples.