Tail 处理器

tail() 处理器是你在编写 Tail Worker 时需要实现的处理器。Tail Worker 可用于实时处理日志，并将其发送到日志或分析服务。

每次调用已连接的 producer Worker 时，都会调用一次 tail() 处理器。

要配置 Tail Worker，请参阅 Tail Workers 文档。

export default {
  async tail(events, env, ctx) {
    fetch("<YOUR_ENDPOINT>", {
      method: "POST",
      body: JSON.stringify(events),
    })
  }
}

from workers import WorkerEntrypoint, fetch
import json

class Default(WorkerEntrypoint):
    async def tail(self, events, env, ctx):
        await fetch("<YOUR_ENDPOINT>", method="POST", body=json.dumps(events))

• events array

  • 一个 TailItems 数组。每个触发 Worker 的事件会收集一个 TailItem。对于在 dynamic dispatch Worker 上安装了 Tail Worker 的 Workers for Platforms 客户，events 将包含两个元素：一个对应 dynamic dispatch Worker，一个对应 User Worker。

• env object

  • 包含与 Worker 关联的绑定（使用 ES modules 格式），例如 KV 命名空间和 Durable Objects。

• ctx object

  • 包含与 Worker 关联的上下文（使用 ES modules 格式）。目前，该对象仅包含 waitUntil 函数。

• event.type string

  • 事件类型。该值始终返回 "tail"。

• event.traces array

  • 一个 TailItems 数组。每个触发 Worker 的事件会收集一个 TailItem。对于在 dynamic dispatch Worker 上安装了 Tail Worker 的 Workers for Platforms 客户，events 将包含两个元素：一个对应 dynamic dispatch Worker，一个对应 user Worker。

• event.waitUntil(promisePromise) : void

  • 请参阅 waitUntil。与 fetch 事件处理器不同，tail 处理器不返回值，因此这是 trace Worker 执行异步工作的唯一方式。

• scriptName string

  • producer 脚本的名称。

• event object

  • 包含 Worker 触发事件的信息。
    • 对于 fetch 事件：FetchEventInfo 对象
    • 对于其他事件类型：目前为 null。

• eventTimestamp number

  • 以 epoch 时间计量。

• logs array

  • 一个 TailLogs 数组。

• exceptions array

  • 一个 TailExceptions 数组。单次 Worker 调用可能产生多个未处理的异常，因为 Worker 可以注册多个异步任务。

• outcome string

  • Worker 调用的结果，取值为：
    • unknown：未设置 outcome 状态。
    • ok：Worker 调用成功。
    • exception：抛出了未处理的异常。可能由多种原因导致，包括：
      • 未捕获的 JavaScript 异常。
      • fetch 处理器未返回 Response。
      • 内部错误。
    • exceededCpu：Worker 调用超出 CPU 限制。
    • exceededMemory：Worker 调用超出内存限制。
    • scriptNotFound：获取 Worker 脚本时发生内部错误。
    • canceled：Worker 调用在完成前被取消。常见原因是客户端在响应发送前断开连接。
    • responseStreamDisconnected：在延迟代理期间响应流断开。当客户端或服务器提前挂断时会发生。

• request object

  • 一个 TailRequest 对象。

• response object

  • 一个 TailResponse 对象。

• cf object

  • 包含来自 IncomingRequestCfProperties 的数据。

• headers object

  • 请求头名称/值条目（默认已脱敏）。请求头名称会转为小写，重复请求头名称对应的值会拼接，并以 ", "（逗号加空格）分隔，与 Fetch 标准 ↗类似。

• method string

  • HTTP 请求方法。

• url string

  • HTTP 请求 URL（默认已脱敏）。

• getUnredacted() object

  • 返回属性未脱敏的 TailRequest 对象

TailRequest 的部分属性默认会脱敏，以降低意外记录敏感信息（如用户凭据或 API token）的风险。脱敏使用启发式规则，因此可能出现误报和漏报。客户端可调用 getUnredacted() 绕过脱敏，但无论是否使用脱敏，都应始终谨慎处理保留的信息。

• 请求头脱敏：当（不区分大小写的）请求头名称为 cookie/set-cookie，或包含子字符串 "auth"、"key"、"secret"、"token" 或 "jwt" 时，请求头值将为字符串 "REDACTED"。
• URL 脱敏：对于 URL 中每个贪婪匹配的 ID 字符子串（a-z、A-Z、0-9、+、-、_），若符合以下 hex 或 base-64 ID 条件，该子串将被替换为字符串 "REDACTED"。
• Hex ID：包含 32 个或更多十六进制数字，且仅包含十六进制数字和分隔符（+、-、_）。
• Base-64 ID：包含 21 个或更多字符，且至少包含两个大写字母、两个小写字母和两个数字。

• status number

  • HTTP 状态码。

记录发送到 console 函数的信息。

• timestamp number

  • 以 epoch 时间计量。

• level string

  • 表示调用的 console 函数的字符串。取值为：debug、info、log、warn、error。

• message object

  • 传递给 console 函数的参数数组。

记录 Worker 调用期间发生的未处理异常。

• timestamp number

  • 以 epoch 时间计量。

• name string

  • 错误类型（例如 Error、TypeError 等）。

• message object

  • 错误描述（例如 "x" is not a function）。

• Tail Workers - 配置 Tail Worker 以接收其他 Worker 的执行信息。