Workers Logs

Workers Logs 可让您自动收集、存储、过滤和分析 Cloudflare Workers 发出的日志数据。数据写入您的 Cloudflare 账户，您可以在仪表板中为每个 Worker 查询。所有新创建的 Worker 默认启用可观测性设置。

日志包括调用日志、自定义日志、错误和未捕获的异常。

要将日志发送到第三方，请使用 Workers Logpush 或 Tail Workers。

您必须为 Worker 添加可观测性设置才能将日志写入 Workers Logs。将以下设置添加到 Worker 的 Wrangler 文件并重新部署 Worker。

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1 // optional. default = 1.
  }
}

[observability]
enabled = true
head_sampling_rate = 1

基于头部的采样（Head-based sampling） 允许您设置记录 Workers 请求的百分比。

环境（Environments） 允许您使用不同配置部署同一 Worker 应用程序。例如，您可能想为 staging 和 production 配置不同的 head_sampling_rate。要为名为 staging 的环境配置可观测性：1. 在 [env.staging] 下添加以下配置

{
  "env": {
    "staging": {
      "observability": {
        "enabled": true,
        "head_sampling_rate": 1 // optional
      }
    }
  }
}

[env.staging.observability]
enabled = true
head_sampling_rate = 1

2. 使用 npx wrangler deploy -e staging 部署 Worker
3. 对每个环境重复步骤 1 和 2。

从 Cloudflare 仪表板访问 Worker 的日志：

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

   Go to Workers & Pages ↗

2. 在 Overview（概览） 中，选择 Worker。

3. 选择 Observability（可观测性）。

要充分利用 Workers Logs，建议使用 JSON 格式记录日志。Workers Logs 会自动提取字段并在数据库中智能索引。这种结构化日志记录技术的优势在于，它允许您轻松按具有无限基数的字段的任何维度分割数据。考虑以下场景：

这些示例之间的区别在于如何索引日志以实现更快的查询。在场景 1 中，user_id 嵌入在消息中。要查找与特定 user_id 相关的所有日志，必须运行文本匹配。在场景 2 和 3 中，可以按 user_id 和 user_email 键筛选日志。

每次 Workers 调用返回一条调用日志，包含 Request、Response 和相关元数据等详情。这些调用日志可通过字段 $cloudflare.$metadata.type = "cf-worker-event" 识别。每条调用日志都会用 Cloudflare 在调用上下文中可用的信息进行丰富。

在 Workers Logs UI 中，日志以本地化时间戳和消息呈现。消息取决于调用处理程序。例如，Fetch 请求的消息描述请求方法和请求 URL，而 cron 事件会列为 cron。以下是调用处理程序及其调用消息列表。

可以在 wrangler 中通过添加 invocation_logs = false 配置来禁用调用日志。

{
	"observability": {
		"logs": {
			"invocation_logs": false
		}
	}
}

[observability.logs]
invocation_logs = false

默认情况下，Worker 会发出包含请求、响应和相关元数据详情的调用日志。

您还可以在整个代码中添加自定义日志。Worker 中的任何 console.log 语句都会在 Workers Logs 中可见。以下示例演示了 Worker 请求处理程序中的自定义 console.log。

export default {
	async fetch(request) {
		const { cf } = request;
		const { city, country } = cf;

		console.log(`Request came from city: ${city} in country: ${country}`);

		return new Response("Hello worker!", {
			headers: { "content-type": "text/plain" },
		});
	},
};

addEventListener("fetch", (event) => {
	event.respondWith(handleRequest(event.request));
});

/**
 * Respond with hello worker text
 * @param {Request} request
 */
async function handleRequest(request) {
	const { cf } = request;
	const { city, country } = cf;

	console.log(`Request came from city: ${city} in country: ${country}`);

	return new Response("Hello worker!", {
		headers: { "content-type": "text/plain" },
	});
}

部署上述代码后，在仪表板或使用实时日志查看 Worker 的日志。

基于头部的采样允许您记录 Cloudflare Worker 传入请求的一定比例。对于高流量应用程序，这有助于减少日志量和管理成本，同时仍提供有意义的应用程序性能洞察。配置基于头部的采样率时，您可以控制被记录的请求百分比。请求上下文内的所有日志都会被收集。

要启用基于头部的采样，在可观测性配置中设置 head_sampling_rate。有效范围为 0 到 1，其中 0 表示一百个请求中零个被记录，1 表示每个请求都被记录。如果未指定 head_sampling_rate，默认配置为 1（100%）。在下面的示例中，head_sampling_rate 设置为 0.01，即每百个请求中记录一个。

{
	"observability": {
		"enabled": true,
		"head_sampling_rate": 0.01 // 1% sampling rate
	}
}

[observability]
enabled = true
head_sampling_rate = 0.01

¹ 每个账户每天有 50 亿条日志的限制。超出 限制后，当天剩余时间将应用 1% 的基于头部采样。

² 单条日志的最大大小限制为 256 KB。超出该大小的日志将被 截断，日志的 $cloudflare.truncated 字段将设置为 true。

Workers Logs 包含在 Free 和 Paid Workers 计划中。

Worker 每月处理 1500 万次请求。每个请求发出 1 条调用日志和 1 条 console.log。head_sampling_rate 配置为 1。

Worker 每月处理 10 亿次请求。每个请求发出 1 条调用日志和 1 条 console.log。head_sampling_rate 配置为 0.1。