Skip to content
Telemetry
Browse docs
Discussion topicsUpdated July 27, 2026Reviewed by the Telemetry editorial and product teams2 min read

Use this doc with your coding agent

Copy an instrumentation prompt into your coding agent and adapt it to your application.

Open prompt packConnect real telemetry
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. Define each field before sending events so queries use the same units, names, and outcomes.

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

Adding a nullable field usually leaves existing queries working. 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.

Try it with your own events

Connect your first real event

Give your coding agent the setup prompt, then run a task in your app. Check that the event arrived and write your first query. You can also try sample data.

Connect real telemetry

No credit card required. Telemetry creates a sample event and query so you can try the dashboard before sending your own data.

  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 feature

Use consistent event names and field types. Check for private data before sending events.

Explore Structured eventsCustomer stories

Page authors and references

The Telemetry editorial team maintains this page. The product team checks the examples and confirms how the product behaves.

How we review our docs