Cloudflare Workers 内置错误监控可直接推给编码 Agent 调查并提 PR

Cloudflare Workers 内置错误监控可直接推给编码 Agent 调查并提 PR | 前端进阶之旅

Full translation

完整中文译文

随着 Agent 协助我们构建更复杂的应用，人类和 Agent 都需要更好的方式来掌握生产环境中出现的问题。编码 Agent 已经可以查询可观测性数据、浏览代码仓库、修改代码、编写测试以及打开 Pull Request。剩下仍需人工完成的环节是串联这些步骤：识别出反复出现的失败是否来自同一个 Bug、收集相关的日志和链路追踪、把这些上下文发送给 Agent，以及验证修复是否生效。没有这种结构化的交接，Agent 必须先搜索原始遥测数据来重建故障的范围和上下文，才能开始调查。

今天，我们正式发布 Issues——Cloudflare Workers 内置的错误监控功能（现已开放公测！），旨在简化上述工作流程。Issues 可以做到：

将反复出现的异常、5xx 响应和错误日志聚合为一个 Issue
将错误、堆栈跟踪、日志、链路追踪和 Worker 版本发送给配置好的编码 Agent
触发 Agent 配置的工作流——从分类 Issue 到查询更多数据再到打开 Pull Request

用以下 Prompt 让你的 Agent 修复你的第一个 Issue，也可以通过 CF CLI 或查阅文档开始上手：

自动捕获失败

只需一行配置，即可开始接收 Worker 上检测到的 Issues，无需额外插桩。Issues 内置于 Workers 运行时，因此无需安装 SDK 或添加应用包装器。

启用后，Issues 会记录未捕获的异常、失败的调用、HTTP 5xx 响应、console.log() 和 console.error() 的输出，以及包含堆栈跟踪的日志。它还会标记失控的告警条件和在循环中写入大量日志的代码。

以一个 Worker 为例，其 handler 在一次部署后开始抛出错误。每个失败请求都有不同的请求 ID，但它们都来自同一个 Bug。Issues 会将它们聚合在一起，并显示错误首次出现的时间、发生次数以及频率是否在上升。

打开一个 Issue 后，你可以看到错误信息、可用的堆栈跟踪、导致错误的日志和链路追踪、Worker 版本、请求详情以及问题随时间的趋势，如下图所示：

为 Agent 补充错误的上下文

Cloudflare 可以捕获 Worker 内部发生的情况，但它不知道哪些用户、账户或会话对你的应用重要。使用 Worker 运行时内置的 OpenTelemetry API 来添加这些标识符，无需安装任何额外包：

import { tracing } from "cloudflare:workers";

export default {
  async fetch(request: Request): Promise<Response> {
    const { userId, accountId, sessionId } = await getAuthDetails(request);
    const span = tracing.getActiveSpan();

    span?.setAttribute("user.id", userId);
    span?.setAttribute("account.id", accountId);
    span?.setAttribute("session.id", sessionId);

    return handleRequest(request);
  },
} satisfies ExportedHandler;

这些标识符会伴随每次发生记录显示。在这个 Issue 中，你现在可以在将其发送给 Agent 之前，看到失败是否集中在某个账户或会话。

将检测到的 Issues 发送给 Agent

一个 Issue 不必再静静地躺在仪表盘里，等着有人复制堆栈跟踪并粘贴到 Prompt 中。只需配置一次自动化，当 Issue 超过发生次数阈值或在一段安静期后再次出现时，Issues 会通过 Automations 直接将其发送给 Agent。你可以选择自动化何时运行以及 Issue 发往何处。

内置编码 Agent：用 routine ID 和 token 连接 Claude Code、用自动化 Webhook URL 连接 Cursor、用 API token 和组织 ID 连接 Devin
通用 Webhook：将 Issue 上下文发送到你自己的 Agent 或 HTTPS 端点
聊天和事件管理：通过聊天或值班工作流通知团队

当自动化运行时，Issues 会发送与该 Issue 一同捕获的故障摘要和诊断上下文——包括异常、错误、经过源码映射的堆栈跟踪、前导和尾部日志与链路追踪、Worker 版本以及你添加的应用上下文。要进行更深入的调查，你可以单独将 Agent 连接到 Cloudflare MCP，让 Agent 查询相关日志和链路追踪，以便提出代码和测试修改并打开 Pull Request。

你对进入生产环境的内容保持控制权：审查 Pull Request、部署修复并将 Issue 标记为已解决。

Issues 如何在一天内发现并解决两个 Workflows Bug

Cloudflare Workflows 是一个支撑长时间运行、多步骤应用的原语，它完全构建在 Workers 平台之上。

在其背后，服务持续跟踪步骤、重试和保存的状态。这使得 Workflows 成为在自身生产系统上测试 Issues 的绝佳场所。开启该功能后一天内，团队就在大量流量中发现了两个不寻常的问题。

卡在重试循环中的迁移：Workflows 控制平面迁移在尝试在边缘情况下应用迁移时，反复遇到 SQLite 外键错误。Issues 使 Workflows 团队能够识别问题并修复它。

从未完成删除的删除流程：Workflows 发现在删除 Workflow 实例时，存在一个边缘情况，会超出 Workers 子请求限制而无法完成删除。Issues 帮助 Workflows 团队识别了问题并进行了修复。

无需让团队去连接数千条独立的遥测数据和用户报告，他们的自动化配置将这些 Issues 直接发送给了 Cloudflare OS，后者顺着错误追溯到 Workflows 代码，并为这两个问题提出了修复方案。

准备开始了吗？

想在你的应用中看看 Issues 能发现什么？按以下步骤上手：

在 wrangler.jsonc 文件中将 observability.issues.enabled 设为 true
在 Cloudflare 仪表盘中设置你的第一个自动化，将 Issues 发送到你选择的目标——无论是 Agent、Webhook、事件管理工具还是聊天平台

如果你的 Agent 正在处理设置，它也可以使用新的 CF CLI 来检查 Issues 和创建自动化。查阅我们的文档了解更多！