追踪

追踪可让您端到端地了解请求在 Workers 应用程序及关联服务中的完整生命周期。这有助于识别性能瓶颈、调试问题并理解复杂的请求流程。通过追踪，您可以回答以下问题：

• 长时间运行的请求原因是什么？
• Worker 发出的子请求需要多长时间？
• 对 KV Namespace 或 R2 bucket 的调用需要多长时间？

Cloudflare Workers 提供开箱即用的追踪插桩——无需修改代码或 SDK。只需在 Worker 上启用追踪，Cloudflare 会自动捕获以下遥测数据：

• Fetch 调用 — 所有出站 HTTP 请求，捕获时序、状态码和请求元数据。这使您能够快速识别外部依赖如何影响应用程序性能。
• 绑定（binding）调用 — 与各种 Worker 绑定的交互，例如 KV 读写、R2 对象存储操作和 Durable Object 调用。
• 处理程序调用 — 每次 Worker 调用的完整生命周期，包括 fetch 处理程序、scheduled 处理程序 和 queue 处理程序 等触发器。

有关完整插桩操作列表，请参阅 spans 和 attributes 文档。

您还可以创建自己的 span 来追踪应用程序特定逻辑。自定义 span 会自动嵌套在内置插桩中，让您对平台操作和自有代码都有端到端的可见性。

更多信息请参阅自定义 span。

通过在 Wrangler 配置文件 中设置 observability.traces.enabled = true 来配置追踪。

{
	"observability": {
		"traces": {
			"enabled": true,
			// optional sampling rate (recommended for high-traffic workloads)
			"head_sampling_rate": 0.05
		}
	}
}

[observability.traces]
enabled = true
head_sampling_rate = 0.05

Workers 追踪遵循 OpenTelemetry (OTel) 标准 ↗。这使得它与 Honeycomb、Grafana Cloud、Axiom 等流行可观测性平台兼容，且无需任何开发工作。如果您的可观测性提供商提供 OpenTelemetry 端点，您可以导出追踪（和日志）！

了解更多关于从 Workers 导出 OpenTelemetry 数据的信息，请点击此处。

通过采样，您可以追踪 Cloudflare Worker 中一定比例的传入请求。 这有助于管理数据量和成本，同时仍能提供有意义的应用程序洞察。

有效采样范围为 0 到 1，其中 0 表示一百次调用中零次被追踪，1 表示每次请求都被追踪， 0.05 这样的数值表示一百次请求中有五次被追踪。

如果未指定采样率，默认为 1，即 100% 的请求将被追踪。

{
	"observability": {
		"traces": {
			"enabled": true,
			// set tracing sampling rate to 5%
			"head_sampling_rate": 0.05
		},
		"logs": {
			"enabled": true,
			// set logging sampling rate to 60%
			"head_sampling_rate": 0.6
		}
	}
}

[observability.traces]
enabled = true
head_sampling_rate = 0.05

[observability.logs]
enabled = true
head_sampling_rate = 0.6

如果您为日志配置了 head_sampling_rate，也可以为追踪设置单独的采样率。

采样采用基于头部的采样（head-based sampling） ↗，意味着未被追踪的请求不会产生任何追踪开销。

Workers 追踪在初始 Beta 期间目前免费。这包括所有追踪功能，如收集追踪、存储追踪以及在 Cloudflare 仪表板中查看追踪。

自 2026 年 3 月 1 日起，追踪将作为 Workers Free、Paid 和 Enterprise 计划用量的一部分计费。每个追踪中的 span 代表一个可观测性事件，与 Workers 日志 共享相同的月度配额和定价：