Tail Workers 说明文档

# Cloudflare Tail Workers 专门用于消费生产者 Worker 执行事件的 Worker，用于日志记录、调试、分析和可观测性。 ## 何时使用此参考 - 为 Cloudflare Workers 实现可观测性/日志记录 - 处理 Worker 执行事件、日志、异常 - 构建自定义分析或错误跟踪 - 配置实时事件流 - 使用尾部处理器（tail handlers）或尾部消费者（tail consumers） ## 核心概念 ### 什么是 Tail Workers？ Tail Workers 自动处理来自生产者 Worker（被监控的 Worker）的事件。它们接收： - HTTP 请求/响应信息 - 控制台日志 (`console.log/error/warn/debug`) - 未捕获的异常 - 执行结果 (`ok`, `exception`, `exceededCpu` 等) - 诊断通道事件 **关键特性：** - 在生产者执行完成后调用 - 捕获整个请求生命周期，包括服务绑定和动态调度子请求 - 按 CPU 时间计费，而非请求数 - 适用于 Workers 付费版和企业版套餐 ### 替代方案：OpenTelemetry 导出 **在使用 Tail Workers 之前，请考虑 OpenTelemetry：** 对于向可观测性工具（Sentry, Grafana, Honeycomb）进行批量导出： - OTEL 导出以批次形式发送日志/追踪（更高效） - 内置与流行平台的集成 - 开销低于 Tail Workers - **仅在需要自定义实时处理时使用 Tail Workers** ## 决策树 需要 Worker 的可观测性吗？ ├─ 批量导出到已知工具 (Sentry/Grafana/Honeycomb)? │ └─ 使用 OpenTelemetry 导出 (而非 Tail Workers) ├─ 需要自定义实时处理吗？ │ ├─ 聚合指标? │ │ └─ 使用 Tail Worker + Analytics Engine │ ├─ 错误跟踪? │ │ └─ 使用 Tail Worker + 外部服务 │ ├─ 自定义日志/调试? │ │ └─ 使用 Tail Worker + KV/HTTP 端点 │ └─ 复杂事件处理? │ └─ 使用 Tail Worker + Durable Objects └─ 快速调试? └─ 使用 `wrangler tail` (不同于 Tail Workers) ## 阅读顺序 1. **[configuration.md](configuration.md)** - 设置 Tail Workers 2. **[api.md](api.md)** - 处理器签名、类型、脱敏 3. **[patterns.md](patterns.md)** - 常见用例和集成 4. **[gotchas.md](gotchas.md)** - 陷阱和调试技巧 ## 快速示例 typescript export default { async tail(events, env, ctx) { // 处理来自生产者 Worker 的事件 ctx.waitUntil( fetch(env.LOG_ENDPOINT, { method: "POST", headers: { "Content-Type": "application/