Workers Logpush

Cloudflare Logpush 支持将 Workers Trace Event Logs 发送到支持的目标。Workers Trace Events Logpush 包括请求和响应的元数据、非结构化 console.log() 消息以及任何未捕获的异常。此产品在 Workers Paid 计划上可用。有关定价信息，请参阅定价。

要配置 Logpush 作业，请验证你的 Cloudflare 账户角色是否可以使用 Logpush。要检查角色：

1. 在 Cloudflare 仪表板中，前往 Members（成员） 页面。

   Go to Members ↗

2. 检查账户权限。具有 Logpush 配置访问权限的角色与 Workers 权限不同。Super Administrators、Administrators 和 Log Share 角色对 Logpush 拥有完全访问权限。

或者，在账户级别创建具有 Logs Edit 权限的新 API 令牌。

要在 Cloudflare 仪表板中创建 Logpush 作业：

1. 在 Cloudflare 仪表板中，前往 Logpush（日志推送） 页面。

   Go to Logpush ↗

2. 选择 Create a Logpush job（创建 Logpush 作业）。

3. 选择目标并根据需要配置。

4. 选择 Workers trace events（Workers 跟踪事件） 作为数据集 > Next（下一步）。

5. 如有需要，自定义数据字段。否则，选择 Next（下一步）。

6. 按照仪表板上的说明验证对数据目标的所有权并完成作业创建。

以下示例将 Workers 日志发送到 R2。有关更多配置选项，请参阅 Logs 文档中的启用目标和 API 配置。

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/logpush/jobs" \
--header 'X-Auth-Key: <API_KEY>' \
--header 'X-Auth-Email: <EMAIL>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "workers-logpush",
  "output_options": {
    "field_names": ["Event", "EventTimestampMs", "Outcome", "Exceptions", "Logs", "ScriptName"],
  },
  "destination_conf": "r2://<BUCKET_PATH>/{DATE}?account-id=<ACCOUNT_ID>&access-key-id=<R2_ACCESS_KEY_ID>&secret-access-key=<R2_SECRET_ACCESS_KEY>",
  "dataset": "workers_trace_events",
  "enabled": true
}' | jq .

在 Logpush 中，你可以配置过滤器和采样率，以更好地控制发送到配置目标的数据量。例如，若只想接收未导致异常的请求日志，在 output_options 下方添加以下 filter JSON 属性：

"filter":"{\"where\": {\"key\":\"Outcome\",\"operator\":\"!eq\",\"value\":\"exception\"}}"

通过在 Wrangler 文件中添加新属性 logpush = true 在 Worker 上启用日志记录。这可以在顶级配置或环境下添加。具有此属性的任何新 Worker 将自动被 Logpush 作业拾取。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// Top-level configuration
	"name": "my-worker",
	"main": "src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"workers_dev": false,
	"logpush": true,
	"route": {
		"pattern": "example.org/*",
		"zone_name": "example.org"
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-08-17"
workers_dev = false
logpush = true

[route]
pattern = "example.org/*"
zone_name = "example.org"

通过 multipart script upload API 配置：

curl --request PUT \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}" \
--header "Authorization: Bearer <API_TOKEN>" \
--form 'metadata={"main_module": "my-worker.js", "logpush": true}' \
--form '"my-worker.js"=@./my-worker.js;type=application/javascript+module'

要通过仪表板启用 Logpush 日志记录：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Worker。

3. 前往 Settings（设置） > Observability（可观测性）。

4. 对于 Logpush，选择 Enable（启用）（仅当你已创建 logpush 作业时可用）。

logs 和 exceptions 字段的组合限制为 16,384 个字符，超过后字段将开始被截断。字符按所有 exception.name、exception.message，然后是 log.message 的顺序计数。

达到字符限制后，所有字段将被截断，一条消息显示 "<<<Logpush: *field* truncated>>>"，然后丢弃日志或异常。

为说明这一点，假设我们的 Logpush 事件如下 JSON，限制为 50 个字符（而非实际的 16,384 限制）。算法将：

1. 计数 exception.names 中的字符：
   1. "SampleError" 和 "AuthError" 共 20 个字符。
2. 计数 exception.message 中的字符：
   1. "something went wrong" 计为 20 个字符，剩余 10 个字符。
   2. 取 "unable to process request authentication from client" 的前 10 个字符并计数，然后截断为 "unable to <<<Logpush: exception messages truncated>>>"。
3. 计数 log.message 中的字符：
   1. 我们已开始截断，因此 "Hello " 将被替换为 "<<<Logpush: messages truncated>>>"，"World!" 将被丢弃。

{
  "Exceptions": [
    {
      "Name": "SampleError",
      "Message": "something went wrong",
      "TimestampMs": 0
    },
    {
      "Name": "AuthError",
      "Message": "unable to process request authentication from client",
      "TimestampMs": 1
    },
  ],
  "Logs": [
    {
      "Level": "log",
      "Message": ["Hello "],
      "TimestampMs": 0
    },
    {
      "Level": "log",
      "Message": ["World!"],
      "TimestampMs": 0
    }
  ]
}

{
  "Exceptions": [
    {
      "name": "SampleError",
      "message": "something went wrong",
      "TimestampMs": 0
    },
    {
      "name": "AuthError",
      "message": "unable to <<<Logpush: exception messages truncated>>>",
      "TimestampMs": 1
    },
  ],
  "Logs": [
    {
      "Level": "log",
      "Message": ["<<<Logpush: messages truncated>>>"],
      "TimestampMs": 0
    }
  ]
}