1. Event contract
One row in api_requests, with the types used by the query made explicit.
- timestamp_utc
- Timestamp
- route_template
- Utf8
- latency_ms
- Float64
- status_code
- Int64
How it works
A reviewable workflow from signal to decision
1
Start from a decision
Write down the operational or product question before selecting columns. A focused question produces a query that can be interpreted and maintained.
2
Inspect the result, not only the syntax
Check volume, nulls, time windows, denominators, and unexpected groups. SQL can execute successfully and still answer the wrong question.
3
Save the query when it stays useful
Turn recurring analysis into a named query, dashboard widget, export, or alert so the team does not recreate it during every incident.
Writing and running SQL in Telemetry
A short capture of the real query editor, autocomplete, result table, and chart workflow.
Boundaries
What this does not replace
- A valid query can still encode the wrong denominator, join, time boundary, or business definition; saved analysis should be reviewed.
- The interactive Query API is designed for analysis, while large extracts should use the asynchronous export path.
- Telemetry exposes DataFusion SQL, so engine-specific functions from another warehouse may need an equivalent expression.
Inspectable proof path
From event contract to a visible answer
This example uses a declared schema, read-only SQL, and deterministic synthetic results. It demonstrates the workflow without presenting sample data as a customer benchmark.
2. Read-only SQL
Which endpoints have the worst tail latency?
SELECT
route_template,
COUNT(*) AS requests,
approx_percentile_cont(latency_ms, 0.50) AS p50_ms,
approx_percentile_cont(latency_ms, 0.95) AS p95_ms,
approx_percentile_cont(latency_ms, 0.99) AS p99_ms
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
AND status_code < 500
GROUP BY route_template
HAVING COUNT(*) >= 50
ORDER BY p95_ms DESC
LIMIT 10;3. Synthetic result
Export requests have the slowest tail and the largest gap between typical and worst-case performance.
| route_template | requests | p50_ms |
|---|---|---|
| /api/reports/export | 50 | 800 |
| /api/projects/:id/sync | 50 | 320 |
| /api/search | 50 | 120 |
Capabilities
What is included
Synchronous JSON queries for interactive analysis
Asynchronous JSON and Parquet exports for larger result sets
Real-time queries that combine fresh buffered events with durable history
Read-only query validation for saved dashboard SQL
Query result charts, tables, exports, and alerts
See the analysis
SQL recipes that use this capability
Calculate p50, p95, and p99 API Latency
Compare median and tail latency by endpoint with DataFusion-compatible percentile SQL.
Open recipeCalculate Weekly Cohort Retention
Group users by first activity week and measure the percentage returning in later weeks.
Open recipeFind Features Used Before Upgrade
Join feature events to upgrade events and rank behaviors that occur before paid conversion.
Open recipeCustomer evidence
How teams use this workflow
Related capabilities
Continue the event-to-decision workflow
Explore
Filter, aggregate, and visualize a table without starting from blank SQL
Explore capabilityShared dashboards
Keep operational and product signals readable in one shared view
Explore capabilityThreshold alerts
Notify people when a queryable signal moves outside its expected range
Explore capabilityStart with one production workflow
Use a focused prompt, send synthetic events, and verify the first useful query before expanding coverage.