Query Logfire Data
When to Use This Skill
Invoke this skill when:
- User wants to query traces, logs, spans, or metrics from Logfire
- User wants to search for specific events, errors, or patterns in telemetry data
- User wants to analyze OpenTelemetry data stored in Logfire
- User wants to add programmatic query capabilities to their code
- User asks to "query logfire", "search traces", "find logs", "get metrics", "count", "summarize", "compare", or "find root cause"
User-Facing Progress
Keep progress updates terse. Do not narrate route classification, local skill instructions, schema selection, or routine query setup. If an update is needed, use one short sentence focused on the action, such as "Querying recent Logfire errors."
Critical Routing: One Workflow Per Request
Before using any query tool, classify the request.
- Query route: "analyze", "query", "count", "summarize", "compare", "find root cause", "find slowest", "look up errors", "get metrics", or "add query capabilities".
- UI route: "open", "show in browser", "show in Codex", "show in Logfire", "live view", "open Explore", "open the UI", "give me a link", or GUI/browser presentation. Use
logfire-ui; do not call query_run just to make a URL.
- Ambiguous route: prompts like "show recent errors", "view logs", or "show spans" do not specify whether the user wants chat analysis or the Logfire UI. Ask the user to choose query analysis or UI view.
- Combined route: if the user explicitly asks for both analysis and a link, query only for the requested analysis or to identify the requested item, then provide the relevant Logfire link. Do not add UI/browser work unless the user asked for it.
Only query before opening Logfire UI when the user asks to open a specific unknown item that must be found first, such as "find the slowest trace and open it" or "open the latest error trace".
Two Approaches
| Aspect |
MCP query_run |
REST API /v1/query |
| Best for |
Interactive analysis in Codex |
Adding query code to a project |
| Auth |
OAuth via MCP session |
Bearer read token |
| Setup |
Already configured via plugin |
Need a read token |
| Formats |
JSON rows |
JSON, CSV, Apache Arrow |
| Default window |
Last 30 min |
Last 24 hours |
| Max range |
14 days |
14 days |
| Row limit |
Must be in SQL |
Default 500, max 10,000 |
Quick Schema Reference
records table (spans and logs)
Key columns for querying:
| Column |
Type |
Description |
start_timestamp |
timestamp (UTC) |
When span/log was created |
end_timestamp |
timestamp (UTC) |
When span/log completed |
duration |
double (seconds) |
Time between start and end; NULL for logs |
trace_id |
string (32 hex) |
Unique trace identifier |
span_id |
string (16 hex) |
Unique span identifier |
parent_span_id |
string (16 hex) |
Parent span; NULL for root spans |
span_name |
string |
Low-cardinality label for similar records |
message |
string |
Human-readable description with arguments filled in |
level |
integer |
Severity (supports level = 'error' string comparison) |
kind |
string |
span, log, span_event, or pending_span |
service_name |
string |
Service identifier |
is_exception |
boolean |
Whether an exception was recorded |
exception_type |
string |
Exception class name |
exception_message |
string |
Exception message |
exception_stacktrace |
string |
Full traceback |
attributes |
JSON |
Structured data; query with ->>'key' |
tags |
string[] |
Grouping labels; query with array_has(tags, 'x') |
http_response_status_code |
integer |
HTTP status code |
http_method |
string |
HTTP method |
http_route |
string |
HTTP route pattern |
otel_status_code |
string |
Span status |
metrics table
| Column |
Type |
Description |
recorded_timestamp |
timestamp (UTC) |
When metric was recorded |
metric_name |
string |
Metric name |
metric_type |
string |
Type (gauge, counter, histogram) |
unit |
string |
Unit of measurement |
scalar_value |
double |
Metric value |
service_name |
string |
Service identifier |
attributes |
JSON |
Metric dimensions |
Full schema: references/schema.md
SQL Syntax
Logfire uses Apache DataFusion (Postgres-like). Key patterns:
-- Time filtering
WHERE start_timestamp > now() - interval '1 hour'
-- JSON attribute access
WHERE attributes->>'user_id' = '123'
SELECT attributes->>'http.url' as url FROM records
-- Nested JSON
attributes->'request'->>'method'
-- Array filtering
WHERE array_has(tags, 'production')
-- Level filtering (string comparison works)
WHERE level = 'error'
-- Case-insensitive matching
WHERE message ILIKE '%timeout%'
-- Time bucketing for aggregation
SELECT time_bucket(interval '5 minutes', start_timestamp) as bucket,
count(*) FROM records GROUP BY bucket ORDER BY bucket
MCP Approach (Interactive)
Call the query_run MCP tool:
query (required): SQL query string
project (optional): target project (default: user's current project)
min_timestamp / max_timestamp (optional): ISO timestamps for time window
Default window is last 30 min. Max range is 14 days. Always include LIMIT in SQL.
Common queries
-- Recent errors
SELECT start_timestamp, message, exception_type, exception_message
FROM records WHERE is_exception LIMIT 20
-- Slow spans
SELECT span_name, duration, start_timestamp
FROM records WHERE duration > 1.0 ORDER BY duration DESC LIMIT 20
-- Endpoint errors
SELECT start_timestamp, message, http_response_status_code
FROM records WHERE http_route = '/api/users' AND level = 'error' LIMIT 20
-- Full trace
SELECT span_name, message, duration, parent_span_id
FROM records WHERE trace_id = '<id>' ORDER BY start_timestamp
-- Error breakdown by service
SELECT service_name, count(*) as errors
FROM records WHERE is_exception GROUP BY service_name ORDER BY errors DESC
UI Links After Querying
If the user explicitly asks for both analysis and a Logfire link, finish the query analysis first, then use a Logfire link only for the known result:
- For a known
trace_id, use project_logfire_link(trace_id=trace_id, project=project, handoff=True) only when the user asked to open it immediately in the browser. Use project_logfire_link(trace_id=trace_id, project=project) for a durable or shareable URL.
- For a project/filter view, use the
logfire-ui routing rules.
- Do not open the browser unless the user asked to open the link.
For a span-count prompt, provide SQL like this when the user wants an aggregate query or analysis:
SELECT
time_bucket(interval '5 minutes', start_timestamp) AS bucket,
count(*) AS span_count
FROM records
WHERE kind = 'span'
GROUP BY bucket
ORDER BY bucket
LIMIT 200
REST API Approach (Programmatic)
Endpoint: GET https://logfire-api.pydantic.dev/v1/query
Region variants:
- US:
https://logfire-us.pydantic.dev/v1/query
- EU:
https://logfire-eu.pydantic.dev/v1/query
Auth: Authorization: Bearer <read_token>
Parameters:
sql (required): SQL query
min_timestamp / max_timestamp (optional): ISO timestamps
limit (optional): row limit (default 500, max 10,000)
Response formats (via Accept header):
application/json — column-oriented JSON (default)
application/json with row_oriented=true param — row-oriented JSON
text/csv — CSV
application/vnd.apache.arrow.stream — Apache Arrow
Python clients: LogfireQueryClient (sync), AsyncLogfireQueryClient (async), logfire.db_api (PEP 249 / pandas).
Detailed examples: references/client-usage.md
Query Best Practices
- Always LIMIT — start with 20, increase as needed
- Use
min_timestamp/max_timestamp params for simple time windows instead of SQL WHERE
- Filter efficiently —
service_name, span_name, trace_id, is_exception are fast filters
- Use
->>'key' for JSON attribute access (returns text); use -> for nested JSON objects
- Avoid
SELECT * — select only the columns you need
- Max 14-day range — queries cannot span more than 14 days
1---
2name: logfire-query
3description: Query and analyze Logfire telemetry data — traces, logs, spans, metrics, summaries, and SQL results. Use this skill when the user asks to "query logfire", "search traces", "find logs", "query data", "search spans", "look up errors in logfire", "get metrics from logfire", "analyze telemetry", "summarize errors", "find root cause", or add Logfire querying capabilities to code. Do not use this skill for direct Logfire UI, browser, live-view, Explore-page, or link-opening requests; use logfire-ui instead. If "show" or "view" wording is ambiguous, ask whether the user wants a UI view or query analysis.
4metadata:
5 source: https://skillmd.com/skills/pydantic/logfire-query
6---
7
8# Query Logfire Data
9
10## When to Use This Skill
11
12Invoke this skill when:
13- User wants to query traces, logs, spans, or metrics from Logfire
14- User wants to search for specific events, errors, or patterns in telemetry data
15- User wants to analyze OpenTelemetry data stored in Logfire
16- User wants to add programmatic query capabilities to their code
17- User asks to "query logfire", "search traces", "find logs", "get metrics", "count", "summarize", "compare", or "find root cause"
18
19## User-Facing Progress
20
21Keep progress updates terse. Do not narrate route classification, local skill instructions, schema selection, or routine query setup. If an update is needed, use one short sentence focused on the action, such as "Querying recent Logfire errors."
22
23## Critical Routing: One Workflow Per Request
24
25Before using any query tool, classify the request.
26
27- Query route: "analyze", "query", "count", "summarize", "compare", "find root cause", "find slowest", "look up errors", "get metrics", or "add query capabilities".
28- UI route: "open", "show in browser", "show in Codex", "show in Logfire", "live view", "open Explore", "open the UI", "give me a link", or GUI/browser presentation. Use `logfire-ui`; do not call `query_run` just to make a URL.
29- Ambiguous route: prompts like "show recent errors", "view logs", or "show spans" do not specify whether the user wants chat analysis or the Logfire UI. Ask the user to choose query analysis or UI view.
30- Combined route: if the user explicitly asks for both analysis and a link, query only for the requested analysis or to identify the requested item, then provide the relevant Logfire link. Do not add UI/browser work unless the user asked for it.
31
32Only query before opening Logfire UI when the user asks to open a specific unknown item that must be found first, such as "find the slowest trace and open it" or "open the latest error trace".
33
34## Two Approaches
35
36| Aspect | MCP `query_run` | REST API `/v1/query` |
37|--------|-----------------|----------------------|
38| **Best for** | Interactive analysis in Codex | Adding query code to a project |
39| **Auth** | OAuth via MCP session | Bearer read token |
40| **Setup** | Already configured via plugin | Need a read token |
41| **Formats** | JSON rows | JSON, CSV, Apache Arrow |
42| **Default window** | Last 30 min | Last 24 hours |
43| **Max range** | 14 days | 14 days |
44| **Row limit** | Must be in SQL | Default 500, max 10,000 |
45
46## Quick Schema Reference
47
48### `records` table (spans and logs)
49
50Key columns for querying:
51
52| Column | Type | Description |
53|--------|------|-------------|
54| `start_timestamp` | timestamp (UTC) | When span/log was created |
55| `end_timestamp` | timestamp (UTC) | When span/log completed |
56| `duration` | double (seconds) | Time between start and end; NULL for logs |
57| `trace_id` | string (32 hex) | Unique trace identifier |
58| `span_id` | string (16 hex) | Unique span identifier |
59| `parent_span_id` | string (16 hex) | Parent span; NULL for root spans |
60| `span_name` | string | Low-cardinality label for similar records |
61| `message` | string | Human-readable description with arguments filled in |
62| `level` | integer | Severity (supports `level = 'error'` string comparison) |
63| `kind` | string | `span`, `log`, `span_event`, or `pending_span` |
64| `service_name` | string | Service identifier |
65| `is_exception` | boolean | Whether an exception was recorded |
66| `exception_type` | string | Exception class name |
67| `exception_message` | string | Exception message |
68| `exception_stacktrace` | string | Full traceback |
69| `attributes` | JSON | Structured data; query with `->>'key'` |
70| `tags` | string[] | Grouping labels; query with `array_has(tags, 'x')` |
71| `http_response_status_code` | integer | HTTP status code |
72| `http_method` | string | HTTP method |
73| `http_route` | string | HTTP route pattern |
74| `otel_status_code` | string | Span status |
75
76### `metrics` table
77
78| Column | Type | Description |
79|--------|------|-------------|
80| `recorded_timestamp` | timestamp (UTC) | When metric was recorded |
81| `metric_name` | string | Metric name |
82| `metric_type` | string | Type (gauge, counter, histogram) |
83| `unit` | string | Unit of measurement |
84| `scalar_value` | double | Metric value |
85| `service_name` | string | Service identifier |
86| `attributes` | JSON | Metric dimensions |
87
88Full schema: [`references/schema.md`](./references/schema.md)
89
90## SQL Syntax
91
92Logfire uses **Apache DataFusion** (Postgres-like). Key patterns:
93
94```sql
95-- Time filtering
96WHERE start_timestamp > now() - interval '1 hour'
97
98-- JSON attribute access
99WHERE attributes->>'user_id' = '123'
100SELECT attributes->>'http.url' as url FROM records
101
102-- Nested JSON
103attributes->'request'->>'method'
104
105-- Array filtering
106WHERE array_has(tags, 'production')
107
108-- Level filtering (string comparison works)
109WHERE level = 'error'
110
111-- Case-insensitive matching
112WHERE message ILIKE '%timeout%'
113
114-- Time bucketing for aggregation
115SELECT time_bucket(interval '5 minutes', start_timestamp) as bucket,
116 count(*) FROM records GROUP BY bucket ORDER BY bucket
117```
118
119## MCP Approach (Interactive)
120
121Call the `query_run` MCP tool:
122- `query` (required): SQL query string
123- `project` (optional): target project (default: user's current project)
124- `min_timestamp` / `max_timestamp` (optional): ISO timestamps for time window
125
126Default window is last 30 min. Max range is 14 days. Always include `LIMIT` in SQL.
127
128### Common queries
129
130```sql
131-- Recent errors
132SELECT start_timestamp, message, exception_type, exception_message
133FROM records WHERE is_exception LIMIT 20
134
135-- Slow spans
136SELECT span_name, duration, start_timestamp
137FROM records WHERE duration > 1.0 ORDER BY duration DESC LIMIT 20
138
139-- Endpoint errors
140SELECT start_timestamp, message, http_response_status_code
141FROM records WHERE http_route = '/api/users' AND level = 'error' LIMIT 20
142
143-- Full trace
144SELECT span_name, message, duration, parent_span_id
145FROM records WHERE trace_id = '<id>' ORDER BY start_timestamp
146
147-- Error breakdown by service
148SELECT service_name, count(*) as errors
149FROM records WHERE is_exception GROUP BY service_name ORDER BY errors DESC
150```
151
152## UI Links After Querying
153
154If the user explicitly asks for both analysis and a Logfire link, finish the query analysis first, then use a Logfire link only for the known result:
155
156- For a known `trace_id`, use `project_logfire_link(trace_id=trace_id, project=project, handoff=True)` only when the user asked to open it immediately in the browser. Use `project_logfire_link(trace_id=trace_id, project=project)` for a durable or shareable URL.
157- For a project/filter view, use the `logfire-ui` routing rules.
158- Do not open the browser unless the user asked to open the link.
159
160For a span-count prompt, provide SQL like this when the user wants an aggregate query or analysis:
161
162```sql
163SELECT
164 time_bucket(interval '5 minutes', start_timestamp) AS bucket,
165 count(*) AS span_count
166FROM records
167WHERE kind = 'span'
168GROUP BY bucket
169ORDER BY bucket
170LIMIT 200
171```
172
173## REST API Approach (Programmatic)
174
175**Endpoint**: `GET https://logfire-api.pydantic.dev/v1/query`
176
177Region variants:
178- US: `https://logfire-us.pydantic.dev/v1/query`
179- EU: `https://logfire-eu.pydantic.dev/v1/query`
180
181**Auth**: `Authorization: Bearer <read_token>`
182
183**Parameters**:
184- `sql` (required): SQL query
185- `min_timestamp` / `max_timestamp` (optional): ISO timestamps
186- `limit` (optional): row limit (default 500, max 10,000)
187
188**Response formats** (via `Accept` header):
189- `application/json` — column-oriented JSON (default)
190- `application/json` with `row_oriented=true` param — row-oriented JSON
191- `text/csv` — CSV
192- `application/vnd.apache.arrow.stream` — Apache Arrow
193
194**Python clients**: `LogfireQueryClient` (sync), `AsyncLogfireQueryClient` (async), `logfire.db_api` (PEP 249 / pandas).
195
196Detailed examples: [`references/client-usage.md`](./references/client-usage.md)
197
198## Query Best Practices
199
2001. **Always LIMIT** — start with 20, increase as needed
2012. **Use `min_timestamp`/`max_timestamp` params** for simple time windows instead of SQL `WHERE`
2023. **Filter efficiently** — `service_name`, `span_name`, `trace_id`, `is_exception` are fast filters
2034. **Use `->>'key'`** for JSON attribute access (returns text); use `->` for nested JSON objects
2045. **Avoid `SELECT *`** — select only the columns you need
2056. **Max 14-day range** — queries cannot span more than 14 days