logfire-query

查询 Logfire 数据

何时使用此技能

在以下情况下调用此技能：

• 用户想要查询 Logfire 中的跟踪、日志、跨度或指标
• 用户想要搜索遥测数据中的特定事件、错误或模式
• 用户想要分析存储在 Logfire 中的 OpenTelemetry 数据
• 用户想要为代码添加程序化查询功能
• 用户要求“查询 Logfire”“搜索跟踪”“查找日志”“获取指标”“计数”“汇总”“比较”或“查找根本原因”

面向用户的进度提示

进度更新应简洁。不要叙述路由分类、本地技能指令、架构选择或常规查询设置。如需更新，请用一句简短的话说明正在执行的操作，例如“正在查询 Logfire 中的近期错误。”

关键路由：每个请求使用一种工作流

使用任何查询工具前，先对请求分类。

• 查询路由：“分析”“查询”“计数”“汇总”“比较”“查找根本原因”“查找最慢的”“查找错误”“获取指标”或“添加查询功能”。
• UI 路由：“打开”“在浏览器中显示”“在 Codex 中显示”“在 Logfire 中显示”“实时视图”“打开 Explore”“打开 UI”“给我一个链接”或图形界面／浏览器展示。使用 logfire-ui；不要仅为生成 URL 而调用 query_run。
• 含糊路由：像“显示近期错误”“查看日志”或“显示跨度”这样的提示，没有说明用户想要聊天分析还是 Logfire UI。请询问用户选择查询分析还是 UI 视图。
• 组合路由：如果用户明确同时要求分析和链接，只针对所需分析执行查询，或查询以确定指定项目，然后提供相关的 Logfire 链接。除非用户提出要求，否则不要额外进行 UI／浏览器操作。

只有当用户要求打开一个必须先找到的特定未知项目时，才应在打开 Logfire UI 前进行查询，例如“找到最慢的跟踪并打开它”或“打开最新的错误跟踪”。

两种方式

方面	MCP query_run	REST API /v1/query
最适合	在 Codex 中进行交互式分析	为项目添加查询代码
身份验证	通过 MCP 会话使用 OAuth	Bearer 只读令牌
设置	已通过插件配置	需要只读令牌
格式	JSON 行	JSON、CSV、Apache Arrow
默认时间范围	最近 30 分钟	最近 24 小时
最大范围	14 天	14 天
行数限制	必须在 SQL 中指定	默认 500，最多 10,000

快速架构参考

records 表（跨度和日志）

查询时常用的列：

列	类型	说明
start_timestamp	timestamp (UTC)	跨度／日志的创建时间
end_timestamp	timestamp (UTC)	跨度／日志的完成时间
duration	double (seconds)	开始与结束之间的时间；日志中为 NULL
trace_id	string (32 hex)	跟踪的唯一标识符
span_id	string (16 hex)	跨度的唯一标识符
parent_span_id	string (16 hex)	父跨度；根跨度为 NULL
span_name	string	相似记录的低基数标签
message	string	填入参数后供人阅读的描述
level	integer	严重级别（支持字符串比较 level = 'error'）
kind	string	span、log、span_event 或 pending_span
service_name	string	服务标识符
is_exception	boolean	是否记录了异常
exception_type	string	异常类名
exception_message	string	异常消息
exception_stacktrace	string	完整堆栈跟踪
attributes	JSON	结构化数据；使用 ->>'key' 查询
tags	string[]	分组标签；使用 array_has(tags, 'x') 查询
http_response_status_code	integer	HTTP 状态码
http_method	string	HTTP 方法
http_route	string	HTTP 路由模式
otel_status_code	string	跨度状态

metrics 表

列	类型	描述
recorded_timestamp	时间戳（UTC）	指标记录时间
metric_name	字符串	指标名称
metric_type	字符串	类型（gauge、counter、histogram）
unit	字符串	计量单位
scalar_value	双精度浮点数	指标值
service_name	字符串	服务标识符
attributes	JSON	指标维度

完整架构：references/schema.md

SQL 语法

Logfire 使用 Apache DataFusion（类似 Postgres）。常见模式：

-- 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 使用方式（交互式）

调用 query_run MCP 工具：

• query（必需）：SQL 查询字符串
• project（可选）：目标项目（默认为用户当前项目）
• min_timestamp / max_timestamp（可选）：时间窗口的 ISO 时间戳

默认时间窗口为最近 30 分钟。最大范围为 14 天。SQL 中始终包含 LIMIT。

常见查询

-- 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 链接

如果用户明确要求同时提供分析和 Logfire 链接，请先完成查询分析，然后仅针对已知结果使用 Logfire 链接：

• 对于已知的 trace_id，只有在用户要求立即在浏览器中打开时，才使用 project_logfire_link(trace_id=trace_id, project=project, handoff=True)。若要获取持久或可分享的 URL，请使用 project_logfire_link(trace_id=trace_id, project=project)。
• 对于项目/筛选视图，请遵循 logfire-ui 路由规则。
• 除非用户要求打开链接，否则不要打开浏览器。

对于 span 数量提示，如果用户需要聚合查询或分析，请提供如下 SQL：

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 使用方式（程序化）

端点：GET https://logfire-api.pydantic.dev/v1/query

区域版本：

• US：https://logfire-us.pydantic.dev/v1/query
• EU：https://logfire-eu.pydantic.dev/v1/query

身份验证：Authorization: Bearer <read_token>

参数：

• sql（必需）：SQL 查询
• min_timestamp / max_timestamp（可选）：ISO 时间戳
• limit（可选）：行数限制（默认 500，最多 10,000）

响应格式（通过 Accept 标头指定）：

• application/json — 面向列的 JSON（默认）
• application/json 搭配 row_oriented=true 参数 — 面向行的 JSON
• text/csv — CSV
• application/vnd.apache.arrow.stream — Apache Arrow

Python 客户端：LogfireQueryClient（同步）、AsyncLogfireQueryClient（异步）、logfire.db_api（PEP 249 / pandas）。

详细示例：references/client-usage.md

查询最佳实践

1. 始终使用 LIMIT — 从 20 开始，按需增加
2. 简单时间窗口使用 min_timestamp/max_timestamp 参数，而不是 SQL WHERE
3. 高效筛选 — service_name、span_name、trace_id、is_exception 是快速筛选条件
4. 使用 ->>'key' 访问 JSON 属性（返回文本）；使用 -> 访问嵌套 JSON 对象
5. 避免 SELECT * — 只选择所需的列
6. 最大范围为 14 天 — 查询范围不能超过 14 天