1. Event schema
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
How to set it up
1
Write down the question
Decide what you need to know before selecting columns. For example, which API routes had the highest error rate in the last hour?
2
Check the results
Check row counts, missing values, time windows, and denominators. Investigate groups you did not expect before saving the query.
3
Save queries you run again
Save the query with a name your team will recognize. Reuse it in a dashboard, export, or alert when the same question comes up again.
Writing and running SQL in Telemetry
Write SQL with autocomplete, inspect the results, and create a chart.
Boundaries
What this does not replace
- SQL can run successfully and still answer the wrong question. Review denominators, joins, time windows, and metric definitions before saving a query.
- Use the interactive Query API for analysis. Use asynchronous exports for large result sets.
- Telemetry exposes DataFusion SQL, so engine-specific functions from another warehouse may need an equivalent expression.
Try the example
Read the schema, SQL, and sample result
This example includes the schema, read-only SQL, and synthetic results. Use it to check how the query works. It does not measure customer results.
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
Queries that combine recent buffered events with stored history
Read-only query validation for saved dashboard SQL
Charts, tables, exports, and alerts from query results
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
Related guides and examples
Start with one production workflow
Use a focused prompt, send synthetic events, and verify the first useful query before expanding coverage.