需要查询和分析 Logfire 遥测数据（traces…

通过 MCP 或 REST API 对 Logfire 中的 OpenTelemetry 数据执行 SQL 查询、错误分析、根因定位和指标统计。

适用场景

解决思路

1. 先对请求分类：若为分析类（analyze、query、count、summarize、compare、find root cause、find slowest、look up errors、get metrics、add query capabilities）走查询路线；若为 UI 类（open、show in browser、show in Codex、show in Logfire、live view、open Explore、open the UI、give me a link）改用 logfire-ui，不要为生成 URL 而调用 query_run；若措辞模糊（如 show recent errors、view logs、show spans）先询问用户要查询分析还是 UI 视图；若用户同时要分析和链接，只做所需分析或定位目标项，再给出对应 Logfire 链接。
2. 仅在用户要求打开某个必须先查找的未知项（如 find the slowest trace and open it、open the latest error trace）时，才先查询再打开 Logfire UI。
3. 保持进度更新简洁，不要叙述路由分类、本地技能指令、schema 选择或常规查询设置；必要时用一句简短说明动作，如“Querying recent Logfire errors.”。
4. 选择查询方式：交互式分析用 MCP query_run（通过 MCP 会话 OAuth 认证，已由插件配置好，返回 JSON 行，默认窗口最近 30 分钟）；向项目添加查询代码用 REST API /v1/query（Bearer read token 认证，支持 JSON、CSV、Apache Arrow，默认窗口最近 24 小时）。两者最大范围均为 14 天，行数上限需在 SQL 中指定（REST 默认 500、最大 10,000）。
5. 查询 records 表（spans 和 logs）时使用关键列：start_timestamp、end_timestamp、duration（秒，日志为 NULL）、trace_id（32 位十六进制）、span_id（16 位十六进制）、parent_span_id（根 span 为 NULL）、span_name、message、level（支持 level = 'error' 字符串比较）、kind（span/log/span_event/pending_span）、service_name、is_exception、exception_type、exception_message、exception_stacktrace、attributes（JSON，用 ->>'key' 查询）、tags（string[]，用 array_has(tags, 'x') 查询）、http_response_status_code、http_method、http_route、otel_status_code。
6. 查询 metrics 表时使用列：recorded_timestamp、metric_name、metric_type（gauge/counter/histogram）、unit、scalar_value、service_name、attributes（JSON 维度）。
7. 使用 Apache DataFusion（类 Postgres）SQL 语法：时间过滤 WHERE start_timestamp > now() - interval '1 hour'；JSON 属性访问 attributes->>'user_id' = '123' 或 SELECT attributes->>'http.url' as url；嵌套 JSON attributes->'request'->>'method'；数组过滤 WHERE array_has(tags, 'production')；级别过滤 WHERE level = 'error'；大小写不敏感匹配 WHERE message ILIKE '%timeout%'；时间分桶 SELECT time_bucket(interval '5 minutes', start_timestamp) as bucket, count(*) FROM records GROUP BY bucket ORDER BY bucket。
8. 调用 MCP query_run 工具：query（必填，SQL 字符串）、project（可选，目标项目，默认用户当前项目）、min_timestamp / max_timestamp（可选，ISO 时间戳）。默认窗口最近 30 分钟，最大范围 14 天，SQL 中始终包含 LIMIT。
9. 使用常见查询模板：最近错误 SELECT start_timestamp, message, exception_type, exception_message FROM records WHERE is_exception LIMIT 20；慢 span SELECT span_name, duration, start_timestamp FROM records WHERE duration > 1.0 ORDER BY duration DESC LIMIT 20；端点错误 SELECT start_timestamp, message, http_response_status_code FROM records WHERE http_route = '/api/users' AND level = 'error' LIMIT 20；完整 trace SELECT span_name, message, duration, parent_span_id FROM records WHERE trace_id = '<id>' ORDER BY start_timestamp；按服务统计错误 SELECT service_name, count(*) as errors FROM records WHERE is_exception GROUP BY service_name ORDER BY errors DESC；span 计数 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。
10. 查询后若用户明确同时要分析和链接：先完成查询分析，再仅对已知结果提供链接——已知 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 路由规则处理；用户未要求打开链接时不要打开浏览器。
11. 使用 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（必填）、min_timestamp / max_timestamp（可选，ISO 时间戳）、limit（可选，默认 500，最大 10,000）；通过 Accept 头选择响应格式：application/json（默认列式 JSON）、application/json 加 row_oriented=true 参数（行式 JSON）、text/csv、application/vnd.apache.arrow.stream。
12. 使用 Python 客户端：LogfireQueryClient（同步）、AsyncLogfireQueryClient（异步）、logfire.db_api（PEP 249 / pandas）。
13. 遵循查询最佳实践：始终加 LIMIT，从 20 开始按需增加；简单时间窗口用 min_timestamp/max_timestamp 参数而非 SQL WHERE；高效过滤使用 service_name、span_name、trace_id、is_exception 等快速过滤字段；JSON 属性访问用 ->>'key'（返回文本），嵌套 JSON 对象用 ->；避免 SELECT *，只选需要的列；查询范围不超过 14 天。

适用边界 · 注意事项

• 不要用于直接打开 Logfire UI、浏览器、live view、Explore 页面或打开链接的请求，这些应使用 logfire-ui。
• 当 show 或 view 措辞有歧义时，不要直接查询，应先询问用户要 UI 视图还是查询分析。
• 用户未要求打开链接时不要打开浏览器；不要仅为生成 URL 而调用 query_run。