您的代理现在可以使用本地追踪调试 Workers
内容提要
Cloudflare 推出本地追踪功能，使 AI 代理能自动调试 Workers。开发时，wrangler dev 或 vite dev 会捕获 OpenTelemetry 追踪，代理可通过 Local Explorer API 查询，无需额外配置。代理能快速定位错误（如 D1 迁移未应用），修复并验证，无需部署或添加临时日志。人类开发者也可在浏览器界面查看追踪数据。
延伸解读
本地追踪如何提升代理调试效率
文章指出，在没有本地追踪时，代理调试一个500错误需要反复添加日志、重跑请求并检查输出，每次循环都消耗时间和令牌。而有了本地追踪，代理能直接查询OpenTelemetry追踪，快速定位失败操作（如D1插入失败），并检查绑定状态和模式，从而在一个本地循环内完成修复和验证。这显著减少了调试周期，提高了开发效率。
自动捕获与无需配置的便利性
该功能的关键优势在于自动化：wrangler dev和vite dev会自动捕获OpenTelemetry追踪，无需安装SDK或手动启用。当检测到代理会话时，开发服务器会自动提示Local Explorer API，代理可通过OpenAPI schema发现端点。这意味着开发者无需在提示中提及可观测性，代理即可利用追踪数据，降低了使用门槛。
本地追踪与云端追踪的互补
文章提到，本地追踪基于与云端相同的workerd运行时，因此本地捕获的追踪与生产环境具有一致性。这允许代理在部署前验证修复，减少因环境差异导致的问题。同时，本地追踪存储在SQLite支持的Durable Object中，通过Local Explorer API提供，与云端仪表板分离，但提供了类似的调试体验。
Q&A
Cloudflare 的本地追踪功能是什么？
Cloudflare 的本地追踪功能是让开发者在本地开发环境中自动捕获 OpenTelemetry 追踪，用于调试 Workers。它通过 wrangler dev 或 vite dev 自动启用，无需额外配置。
如何启用本地追踪功能？
只需更新 Wrangler 或 Cloudflare Vite 插件到最新版本，然后正常使用 wrangler dev 或 vite dev 启动本地开发服务器即可。无需安装 SDK 或配置追踪。
AI 代理如何自动发现并使用本地追踪？
当开发服务器检测到 AI 代理会话时，会自动打印提示，告知代理 Local Explorer API 的地址。代理可以通过该 API 的 OpenAPI schema 自动发现可用端点，并查询追踪数据。
本地追踪能捕获哪些数据？
本地追踪能捕获 Fetch 调用、绑定调用（如 KV、R2、D1、Durable Objects、Queues 等）以及处理器调用的完整生命周期，还包括自定义 span 和相关的控制台日志。
如何使用 Local Explorer 查看追踪数据？
在本地开发服务器中按 'e' 键或访问 /cdn-cgi/explorer 打开 Local Explorer 界面，可以查看请求的 spans、时间、属性、错误和相关日志。
本地追踪如何帮助调试 D1 迁移问题？
通过本地追踪，代理可以查看 D1 操作失败的具体错误，如 'no such column: delivery_window'，然后使用 Local Explorer API 检查 D1 schema，发现迁移未应用，应用迁移后重新测试即可修复。
本地追踪与 Workers Tracing 的关系是什么？
本地追踪基于 Workers Tracing 的运行时 instrumentation，该 instrumentation 直接内置于 workerd 运行时，无需 SDK 即可捕获 spans。Wrangler 和 Vite 插件使用 Miniflare 在本地运行相同的运行时，因此本地开发也能获得相同的追踪能力。
