wrangler dev支持本地追踪：Agent可无部署调试Workers

从今天起，wrangler dev 和 vite dev 会自动捕获本地 Worker 调用产生的 OpenTelemetry 追踪数据。当 Cloudflare 的工具检测到 Agent 会话时，它会将 Agent 指向 Local Explorer API——一个本地调试 API，Agent 可以通过它查询这些追踪数据。你不需要安装任何 SDK、启用追踪功能、配置 Agent，甚至不需要在提示词中提及可观测性。

提示词可以简单到如下：

POST /api/orders is returning 500. Find the cause, fix it, and verify the fix locally.

这一功能建立在多年对本地开发的投入之上，从引入 Miniflare 到在 Wrangler 3 中将本地模式设为默认。Local traces 在代码部署之前，为编程 Agent 提供了来自开发环境的结构化反馈。

Agent 自动发现 Local Explorer API

作为其正常工作流程的一部分，Agent 启动 wrangler dev 或 vite dev 来运行和测试 Worker。当开发服务器识别到支持的编程 Agent 会话时，它会自动打印一条提示，如下所示：

This dev session is running in an AI agent.

The Local Explorer API is available at
http://localhost:8787/cdn-cgi/explorer/api

... 

Debug with traces:
POST /cdn-cgi/explorer/api/local/observability/query -- query traces and logs with SQL

Local Explorer 是一个基于浏览器的界面和 REST API，用于在开发期间查看和编辑本地资源数据以及查询可观测性数据。API 根路径提供一个 OpenAPI schema，使 Agent 能够在运行时发现可用端点，而无需硬编码的指令。

自动捕获的追踪数据可通过该 API 中的只读可观测性端点访问，并与它们关联的 console 日志一起提供。Agent 可以查询这些遥测数据，然后使用 API 的其他操作来检查本地 Worker 和 binding，或查看 D1、KV、R2、Durable Objects 和 Workflows 中的状态。

找到失败并验证修复

以 POST /api/orders 为例，它从 KV 中检索活跃购物车，将结账详情保存到 D1，然后向 Queue 发送一条消息进行处理。在 schema 变更之后，该端点突然开始返回 500 状态。

500 状态无法确定是哪个操作失败了。Agent 在 KV、D1 和 Queue 周围添加日志，重新运行请求，检查输出，然后重复这个过程。每个周期都需要时间并消耗 token，因为 Agent 要从文本中重建请求。

Agent 重现错误并查询只读可观测性端点。追踪显示 KV 读取成功，D1 插入失败并提示 no such column: delivery_window，而 Queue 从未被调用。Agent 使用 Local Explorer API 访问与你在此处看到的相同的追踪数据：

Agent 使用 API 检查 D1 schema。它发现添加 delivery_window 的迁移存在于仓库中，但尚未在本地应用，于是应用该迁移，再次发送请求，并查询新的追踪。问题已解决。

在一个本地循环中，Agent 识别出失败的操作，修复本地环境，并验证结果，无需部署或添加临时日志。

在 Local Explorer 中探索追踪和日志

Agent 通过 API 查询本地遥测数据，但作为人类，你可以在 Local Explorer 中可视化相同的数据——这是一个内置于本地开发服务器中的基于浏览器的界面。除了浏览本地 binding 状态外，你还可以选择一个请求来检查其 spans、时序、属性、错误和关联的 console 日志。

Local Explorer 运行在与你的 Worker 相同的 localhost origin 上，而非 Cloudflare 仪表板中。在 Wrangler 中按 e 键或访问本地服务器上的 /cdn-cgi/explorer 来打开它。

当我们发布 Workers Tracing 时，我们将 instrumentation 直接构建到了 workerd 中——这是驱动 Workers 的开源运行时。无需 SDK 或任何代码更改，运行时即可捕获以下 spans：

• Fetch 调用：所有出站 HTTP 请求，包括时序、状态码和请求元数据。
• Binding 调用：与 KV、R2、D1、Durable Objects、Queues 和其他 binding 的每次交互。
• Handler 调用：每次调用的完整生命周期，从 fetch 到 scheduled 再到 queue handlers。
• 应用程序发出的任何自定义 spans 也会与这些自动 spans 一起显示。

Wrangler 和 Cloudflare Vite 插件使用 Miniflare 在同一运行时中本地运行 Worker，使这些 instrumentation 在本地开发期间可用。

Miniflare 收集运行时事件和 console 输出，将它们组装成 OpenTelemetry 追踪和关联日志，然后将遥测数据写入一个内部 SQLite 支持的 Durable Object，作为本地追踪存储。Local Explorer API 通过本地开发服务器暴露这些数据，Agent 可以轻松查询追踪和日志并检查本地状态。

更新 Wrangler 或 Cloudflare Vite 插件，具体使用哪个取决于你的项目：

# Wrangler
npm install --save-dev wrangler@latest

# Cloudflare Vite plugin
npm install --save-dev @cloudflare/vite-plugin@latest

然后像平常一样让 Agent 在本地调试。Agent 已经能够本地编写和运行 Worker——现在它可以看到发生了什么、修复失败的地方，并在部署之前验证结果。查看文档了解更多！