第22章 使用 Logfire MCP 服务器在 Cursor 中调试生产环境
什么是 Logfire MCP server?
Logfire MCP server 是一个托管的 Model Context Protocol 服务,把你的 OpenTelemetry trace、日志和指标暴露给任何 MCP 客户端。美国项目使用 https://logfire-us.pydantic.dev/mcp,欧盟项目使用 https://logfire-eu.pydantic.dev/mcp(对应不同的 Logfire 实例),认证方式为浏览器 OAuth,或使用 Logfire API key 作为 bearer token。
它提供 51 个工具,覆盖查询、仪表盘、告警、通知渠道、issue 和 feature-flag 变量。其中一个几乎承担了全部工作:参与开发的 Marcelo 说 query_run 占了所有调用的 99% 以上,因为 Pydantic Logfire 把 span 存成 SQL 表,这让排查变得容易得多——agent 写 SQL 非常在行。
怎么设置 Logfire MCP server?
接入方式有三种,每种都不超过一分钟。选和你编辑器对应的那一行:
| 客户端 | 接入方式 |
| Claude Code | /plugins,然后从官方 marketplace 安装 logfire |
| Codex | 从 OpenAI plugin marketplace 安装 Logfire,或通过 CLI 添加 |
| Cursor 及其他 | 在 MCP 配置里填远程 server URL |
如果你用 Claude Code:运行 /plugins,找到 logfire,安装,然后在浏览器里认证。你会同时获得 MCP server 和一组 skills,用于查询、埋点和在 Logfire UI 中导航。
Codex 用户可以从 OpenAI marketplace 上的 Logfire plugin 获得同样的内容:打开页面、安装、登录。CLI 方式则通过已发布的 pydantic/skills marketplace 安装同一个插件:
codex plugin marketplace add pydantic/skills --ref main
codex plugin add logfire@pydantic-skills
codex mcp login logfire
之后开一个新的 Codex 会话,MCP 工具就会加载。
其他环境直接指向远程 server 即可。不需要把 token 粘贴到以后可能被提交进仓库的文件里。对 Cursor 来说,就是在项目根目录的 .cursor/mcp.json 里配置:
{
"mcpServers": {
"logfire": {
"url": "https://logfire-us.pydantic.dev/mcp"
}
}
}
如果项目在欧盟区域就用 https://logfire-eu.pydantic.dev/mcp,自托管的话用自己的 URL。Claude Code 不用插件的话只需两条命令:
claude mcp add --transport http logfire https://logfire-us.pydantic.dev/mcp
claude mcp login logfire
在 CI、容器或没有浏览器的环境里,用 Logfire API key 作为 bearer token 认证。读取权限覆盖下文写到"写入"部分之前的所有内容。
然后验证一下。开场可以问:"能帮我看下 Logfire 里有没有数据吗?"你应该收到项目名和行数。在演示视频里,Claude 还主动多做了一步,跑了一个按服务分组、统计异常数量的查询——因为它能看到自己有哪些工具可用。
Logfire MCP server 为什么用 SQL?
Logfire 用 SQL,是因为模型写 SQL 比操作专有的查询 API 靠谱得多。Logfire 基于 OpenTelemetry 构建,把 span 存在可查询的 records 表里,所以 agent 不用学什么过滤 DSL,也不用猜下拉框里有什么词汇。
这个设计决策解释了为什么 query_run 承载了 99% 以上的流量,也解释了为什么它有一套覆盖多个模型和编码 agent 的 eval 测试集。工具描述会指示 agent 在没有 schema 参考时先去获取一份,所以 schema 对齐无需你做任何配置。幻觉出来的列名是可观测性查询失败的主因,这就是解法。
排查一个故障接口的第一步查询大致长这样:
SELECT start_timestamp,
http_route,
http_response_status_code,
exception_type,
exception_message,
trace_id
FROM records
WHERE is_exception
AND http_route = '/api/chat'
ORDER BY start_timestamp DESC
LIMIT 20
你很少会自己写这种查询,但应该能看懂。Marcelo 的做法是:不纠结 SQL 本身,主要让 agent 把查询解释回来。
有几点注意:Logfire 的方言是 DataFusion,模型有时会顺手用到它们更熟悉的方言(比如 ClickHouse)里的函数。另外在 span 很多的项目里,agent 无人干预时会愉快地查询两个月的数据,哪怕它只需要最近一小时。
后一种情况有检查层兜底:当查询规划器看出某个查询会跑很久,它会直接快速失败并返回工具错误。agent 把错误当作输出读取,缩小时间窗口或加个过滤条件再重试。这种重试非常频繁,用户基本感知不到。
一次调试会话是什么样的?
演示应用是一个让 LLM agent 互相辩论的论坛,用 Logfire 埋点,并预置了真实异常。整个流程分六步:
- 发现问题。开场问题只是"有没有数据"。回答里已经主动列出了异常,包括一个 ZeroDivisionError。
- 修复它。"调查并修复这个除零错误。"agent 查询异常、从 span 中拿到堆栈和具体行号、打开文件、加上防护,并删掉了那段永远走不到的 handler。
- 问一个堆栈回答不了的问题。Laura 问论坛里哪个 agent 最啰嗦。答案是 historian——见过 historian 的人都不会意外。
- 把一次性查询固化。"创建一个展示各 agent 冗长度随时间变化的仪表盘。"它建了一个按 agent 每轮平均可见输出 token 数来度量的仪表盘,并按要求加了面板描述。
- 加告警。Marcelo 没有直接指定,而是要了个建议:"最近出了很多 500,能不能给我建议一个告警?"agent 提议了一个按服务和路由过滤、统计 5xx 状态码数量超过 20 次的查询,并创建了它。
- 闭环。要求创建一个指向 ngrok 隧道的通知渠道,agent 也建好了 webhook 渠道。远端接收端被配置成在收到告警负载时启动一个只读工具的编码 agent。Claude 配置了一个给自己 page 的告警。
除了错误还能问什么?
用 Logfire MCP 能回答的有些问题,是你不会专门为它建仪表盘面板的:每个路由的 token 数、某条代码路径到底有没有被执行。没人应该为只打算问一次的问题专门画一张图。
按模型和操作统计延迟,用于发现 provider 悄悄劣化的情况:
SELECT attributes->>'gen_ai.request.model' AS model,
attributes->>'gen_ai.operation.name' AS operation,
count(*) AS spans,
avg(duration) AS avg_duration
FROM records
WHERE attributes->>'gen_ai.request.model' IS NOT NULL
GROUP BY model, operation
ORDER BY avg_duration DESC
所有 gen_ai.* 下的字段都能这样切片,所以 token 数、provider、工具名称、模型推理过程和你的 HTTP span 在同一张表里。只要能在 Logfire UI 的 span 里显示的内容,你的 agent 就能查询,包括推理 trace。
另一个值得养成的习惯是问某条代码路径有没有被执行。听起来简单到没用的程度,但它能抓到那种 CI 全绿、合并成功、上线后却什么都没做的部署。
Logfire MCP server 能写吗?
能,工具面板既有读也有写能力。拥有相应写权限的 agent 可以创建和修改五类对象,并管理第六类:
- 仪表盘,包括面板、变量和布局分组
- 告警,包括查询、阈值和评估窗口
- 通知渠道,webhook 和 Opsgenie
- 托管 feature-flag 变量,包括版本、标签和灰度发布
- 通知计划
- issue 状态——只能变更已有 issue 的状态,不能新建 issue
当你修完一次事故,你清楚地知道哪个信号本可以提前发现它,而这种记忆的半衰期大概只有一天。趁信号还没忘就创建告警,才是真正提升系统韧性的做法。这是今天的你在为明天的问题做准备。
关于凭证有两条提醒。agent 删除仪表盘和创建一样熟练,所以只在会话需要时才授予写权限。读 token 也并非无害:trace 和日志里携带用户可控的内容、模型负载和工具参数,agent 可能把它们暴露到不该去的地方,或者当成指令来执行。读和写都要收窄范围、妥善保护。
什么时候该让 agent 写 Python?
当一个任务需要串联大约三个以上查询时,就该用 exec 工具了。六次顺序工具调用意味着六次往返,每次返回的 JSON 模型都得先读一遍才能决定下一步,全都堆积在上下文里。
Logfire 的代码执行端点就是为此而生的。它是独立于那个 51 工具 server 的另一个 MCP server,总共只有三个工具:exec 接收 Python 代码,在服务端的 Monty 里运行,那 51 个工具在沙箱里全被封装成函数;help 让 agent 发现这些函数是什么;results 取回之前运行的输出。只有打印出来的摘要会经过网络。取告警、用 asyncio.gather 拉取指标、trace 和部署记录、做关联,最后打印四行结果。中间数据完全不进入你的上下文窗口。
节省非常可观。Anthropic 报告过在类似场景下从 150,000 token 降到 2,000,减少 98.7%;Cloudflare 发现对其 2500 个端点的 API 做完整 MCP 实现会在用户发出第一条消息前就消耗 117 万 token。Jiri 在 Your agent would rather write code 里写了我们的版本,结论是:在多步组合场景中 decisively 胜出,而单次查询还是直接调用工具更快。
Logfire MCP server 的局限在哪里?
Logfire MCP server 能定位出现在单条 trace 里的 bug,但找不到只在跨文件模式中显现的 bug。有四个限制值得了解:
- trace 直接指向某一行是最理想的情形。证据集中在单个文件时 agent 表现极佳,比如那个除零修复。但"同样的缺失清理逻辑出现在九个组件里"这种问题它就弱得多,因为单条 trace 里没有任何线索引导它去找这个模式。
- 提交了修复不等于修复生效。agent 知道代码改了,却不知道生产环境之后发生了什么。一天后再查一次 trace,对比预期与实际。AutonomyAI 把这一步自动化了,他们的 12 次静默空转部署就是这么发现的。
- 让 agent 多问澄清问题。Laura 的建议是告诉 agent"这个查询感觉不太对"并让它解释自己,或者问一个告警查询:哪些条件会触发、哪些不会。塞满嵌套 CTE 的长查询通常意味着模型把事情搞复杂了。
- 数据对齐能抬高下限。模型会基于真实 span 的信息进行论证,但它仍然会从那些悄悄排除了半数流量的查询中得出自信的结论。
哪些团队在生产中使用 Logfire MCP server?
Dosu 和 AutonomyAI 都把 Logfire MCP server 作为主要的调试入口。Dosu 报告的是省下的时间,AutonomyAI 报告的是抓住的回归。
Dosu 用 54 个 agent 跑了超过 697,000 次生产运行,大部分调试都在编码 agent 里完成而不是 Logfire UI。有些 trace 超过 25 分钟,手动滚动查看是很大的工作量。在 MCP server 改变工作流之前的某个 14 天周期里,团队用这种方式查了 193 条生产 trace。
能在编码 agent 里直接提问并拿到带引用的指标,这太有价值了。除非问题真的很棘手,我很少需要真正打开 Logfire 深挖。—— Taylor Dolezal,Dosu 开源负责人
Dosu 估算调试时间缩短了 90%,定位根因的时间从约一小时降到几分钟,并归功于 Logfire 的 agents 仪表盘帮他们发现了每年价值超过 3 万美元的 prompt 缓存 bug。
AutonomyAI 则让自己的 agent 接入它。他们的 agent 在开发时查询 Logfire 来确认代码路径的实际行为,并在变更合并后的几天里再次查询。五周内,这个合并后检查流程覆盖了 105 个已合并 PR,从真实流量中发现了 65 个问题,还抓到 12 个合并全绿却静默空转的部署。Logfire 三周内处理了超过 3500 万个 span,运行成本约是旁边那套 Datadog 部署的 1/3.5。
我们大多数工程师和内部系统现在几乎所有事情都用 Logfire MCP。我们几乎不打开 Logfire UI 了,因为 MCP 实在太好用。—— Tammuz Dubnov,AutonomyAI 联合创始人兼 CTO
如何开始?
安装插件或添加 URL,完成认证,然后问你的 agent:"这周生产环境出了什么问题?"如果你还没上报 trace,Logfire 文档覆盖了 Python、JavaScript、Rust 以及任何支持 OpenTelemetry 的技术栈。免费套餐足够回答这个问题。
你的编码 agent 早已把你的代码烂熟于心。把代码本身告诉不了它的那部分交给它吧。
常见问题
什么是 Logfire MCP server?
Logfire MCP server 是一个托管的 Model Context Protocol 服务,把 Pydantic Logfire 的 OpenTelemetry trace、日志和指标暴露给 Cursor、Claude Code、Codex 等 MCP 客户端。它让编码 agent 用 SQL 查询生产数据并返回附带 trace ID 的答案,全程无需任何人打开 Logfire UI。
如何在 Cursor 中连接 Logfire MCP?
在项目根目录的 .cursor/mcp.json 中添加远程 server,URL 用 https://logfire-us.pydantic.dev/mcp,欧盟项目用 https://logfire-eu.pydantic.dev/mcp。Cursor 第一次调用工具时会提示浏览器认证。本地无需安装任何东西。
Logfire MCP server 支持 Claude Code 和 Codex 吗?
支持。Claude Code 有官方 marketplace 插件,运行 /plugins 选择 logfire 即可安装,包含 MCP server 以及用于查询、埋点和导航 Logfire 的 skills。Codex 可以从 OpenAI marketplace 的 Logfire plugin 安装同样的内容,或通过 CLI 添加 pydantic/skills marketplace,运行 codex plugin add logfire@pydantic-skills,然后 codex mcp login logfire。
AI agent 对生产 trace 写 SQL 可靠吗?
大体可靠,但有两种已知的失败模式:模型有时会用到其他 SQL 方言的函数(Logfire 用的是 DataFusion 方言),有时会申请远超需要的时间窗口。query_run 的工具描述会指示 agent 查询前先获取 schema 参考,而且 Logfire 会让耗时过长的查询快速失败,agent 就会收窄窗口重试。
Logfire MCP server 能创建仪表盘和告警吗?
能。除了查询,它还能创建和编辑仪表盘、告警、通知渠道、通知计划和托管 feature-flag 变量,并变更已有 issue 的状态。这让一次调试会话可以以永久监控收尾,而不是只得到一次性的答案。注意两端的权限都要谨慎收窄:agent 删除仪表盘和创建一样容易,而仅有读权限也会暴露 trace 中携带的用户内容。
Logfire MCP server 能省多少时间?
Dosu 报告调试时间减少 90%,在 54 个 agent、超过 697,000 次生产运行中,定位根因的时间从约一小时降到几分钟。AutonomyAI 的合并后检查在五周内发现了 65 个问题,并抓到 12 个静默失败的部署。
Logfire 需要 Python 或 Pydantic AI 吗?
不需要。Logfire 基于 OpenTelemetry 构建,可以摄入任何输出 OTel 数据的技术栈的 trace,包括 JavaScript、Rust 和 Go。Pydantic AI 内置了 Logfire 埋点,让接入只需一步,但并非必需。