Telemetry
Browse docs
Discussion TopicsUpdated July 27, 2026Reviewed by the Telemetry editorial and product teams2 min read

Use this doc with your coding agent

Open a focused prompt pack for Claude Code, Codex, Cursor, or another coding agent, then adapt it to the workflow covered here.

Open prompt packStart with sample data
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.

Put this guide to work

Run your first query in under a minute

Create a sample event to explore immediately, or connect your real application with the agent prompt.

Start with sample data

No credit card required. A clearly marked sample event and ready-to-run query are created automatically, so no production data is needed to evaluate the workflow.

  1. 1. Create one clearly marked sample event
  2. 2. Open the ready-to-run query
  3. 3. Save the result to your dashboard

Related product capability

Capture stable event names, typed fields, and privacy-reviewed context.

Explore Structured eventsCustomer evidence

Ownership and technical references

The Telemetry editorial team owns this explanation; the product team reviews behavior, examples, and boundaries.

Review the editorial standard