Last updated:
Use SQL in Chat
SQL is what Agent0 uses when a question requires more than a direct log search, span search, or metric query can express. When you ask a question that involves joining signals, counting distinct entities, or aggregating across multiple dimensions, Agent0 writes and runs a SQL query behind the scenes — you never write or run any yourself.
Agent0 uses an SQL subset optimized for observability data, with access to three tables: logs, spans, and web_events.
What Agent0 Uses SQL For
Agent0 reaches for SQL when PromQL and the dedicated log and span tools aren't enough on their own:
- Join signals — correlate spans with their log messages using
trace_id - Count distinct entities — unique users, sessions, IPs, or services in a time window
- Aggregate across dimensions — group error counts by service, severity, or operation
- Search free text — find patterns across log bodies or attribute values
- Rank and compare — top N services by error rate, slowest operations, most affected users
For simpler questions — "show me recent error logs", "find failing spans" — Agent0 uses the dedicated log and span tools instead, which are faster and return richer formatted results.
Example Requests
| You ask | What Agent0 runs |
|---|---|
| "Count error logs per service in the last hour" | A SQL query that groups logs by service name and counts where severity is ERROR |
| "Show me error spans alongside the logs they generated" | A SQL query that LEFT JOINs spans and logs on trace_id, filtered to error spans |
| "How many unique users encountered an error today?" | A SQL query that counts distinct user IDs from web events where the event is an error |
| "What are the top 10 most common error messages?" | A SQL query that groups log bodies by frequency and returns the highest counts |
| "Show me average latency and request count per endpoint for the checkout service" | A SQL query that groups span duration by operation name and calculates averages and counts |
For latency percentiles such as p95, Agent0 uses PromQL. The SQL subset does not support percentile or quantile functions.
Further Reading
- Investigation & Analysis - How Agent0 uses tools during investigations
- Key Concepts - Reference terminology and mental model