1. Event contract
One row in agent_events, with the types used by the query made explicit.
- timestamp_utc
- Timestamp
- event_name
- Utf8
- data.tool_name
- Utf8
- data.status
- Utf8
- data.args.operation
- Utf8
- data.latency_ms
- Float64
How it works
A reviewable workflow from signal to decision
1
Choose one completed workflow
Start where a user, worker, API, webhook, or agent produces a meaningful outcome. A small event at the boundary is easier to trust than a giant payload.
2
Log the fields future questions need
Include stable identifiers, status, duration, environment, feature, and categorized error context. Keep secrets and raw private content out.
3
Verify the table before expanding
Send synthetic test events, inspect the inferred schema, and run the first query. Add more coverage only after the event contract is useful.
Structured event tables in Telemetry
An actual Telemetry workspace showing ingested event tables and the query surface used to verify them.
Boundaries
What this does not replace
- Telemetry does not decide which personal or regulated data your organization is allowed to collect; the event contract still needs an owner and retention policy.
- Automatic schema evolution cannot repair ambiguous event names, inconsistent units, or identifiers that change meaning between producers.
- Structured events complement traces and database-native diagnostics; they are not a substitute for every low-level debugging signal.
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 AI tools and arguments are associated with the most failed calls?
SELECT
"data.tool_name" AS tool_name,
"data.args.operation" AS operation,
COUNT(*) AS calls,
SUM(CASE
WHEN "data.status" = 'failed' THEN 1 ELSE 0
END) AS failures,
100.0 * SUM(CASE
WHEN "data.status" = 'failed' THEN 1 ELSE 0
END) / NULLIF(COUNT(*), 0) AS failure_rate_pct,
approx_percentile_cont("data.latency_ms", 0.95) AS p95_latency_ms
FROM agent_events
WHERE event_name = 'agent_tool_called'
AND timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY "data.tool_name", "data.args.operation"
HAVING COUNT(*) >= 20
ORDER BY failure_rate_pct DESC, calls DESC;3. Synthetic result
CRM lookup is both the least reliable tool operation and the slowest at p95.
| tool_name | operation | calls |
|---|---|---|
| crm_lookup | search_contact | 842 |
| order_api | fetch_order | 2210 |
| knowledge_search | semantic_search | 4510 |
Capabilities
What is included
HTTP ingestion API plus JavaScript, Python, Go, and Rust SDKs
Nested JSON fields exposed as queryable dotted columns
Schema compatibility checks before events enter the live buffer
Automatic UTC timestamp field for time-series analysis
Read, write, and read-and-write API-key scopes
See the analysis
SQL recipes that use this capability
Query Nested AI Tool-Call Events
Filter dotted nested fields and rank failing tools without flattening the original event payload.
Open recipeDetect Missing Service Heartbeats
Find services, workers, or scheduled tasks that stopped reporting before a failure event appeared.
Open recipeCalculate API Error Rate by Route
Use SQL to rank API routes by 5xx error rate while protecting the result from low-volume noise.
Open recipeCustomer evidence
How teams use this workflow
“Telemetry is one of the easiest ways to go from dumping in your data to actually understanding it.”
Shayan Taslim, LogSnag
Review the documented workflow“Telemetry makes it super easy to track, analyze, and visualize what's going on in my business. It's the perfect mix of simple and powerful.”
Namu Kang, Browserflow
Review the documented workflowRelated capabilities
Continue the event-to-decision workflow
SQL workbench and Query API
Ask detailed questions with the same SQL humans and agents can inspect
Explore capabilityExplore
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 capabilityStart with one production workflow
Use a focused prompt, send synthetic events, and verify the first useful query before expanding coverage.