跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Tail 处理器

最后更新 查看 MarkdownAgent 设置

背景

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 执行异步工作的唯一方式。

TailItems

属性

  • scriptName string

    • producer 脚本的名称。
  • event object

    • 包含 Worker 触发事件的信息。
  • eventTimestamp number

    • 以 epoch 时间计量。
  • logs array

  • 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:在延迟代理期间响应流断开。当客户端或服务器提前挂断时会发生。

FetchEventInfo

属性

TailRequest

属性

  • cf object

  • 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 个或更多字符,且至少包含两个大写字母、两个小写字母和两个数字。

TailResponse

属性

  • status number

    • HTTP 状态码。

TailLog

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

属性

  • timestamp number

    • 以 epoch 时间计量。
  • level string

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

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

TailException

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

属性

  • timestamp number

    • 以 epoch 时间计量。
  • name string

    • 错误类型(例如 Error、TypeError 等)。
  • message object

    • 错误描述(例如 "x" is not a function)。

相关资源

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

这篇文档对您有帮助吗?