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

追踪

最后更新 查看 MarkdownAgent 设置

什么是 Workers 追踪?

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

  • 长时间运行的请求原因是什么?
  • Worker 发出的子请求需要多长时间?
  • 对 KV Namespace 或 R2 bucket 的调用需要多长时间?
示例追踪,显示对蛋糕店的 POST 请求,包含多个 span(fetch 请求和 Durable Object 操作)

自动插桩

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

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

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

自定义 span

您还可以创建自己的 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

将 OpenTelemetry 追踪导出到第三方目标

Workers 跟踪遵循 OpenTelemetry (OTel) 标准 ↗,因此无需你投入开发工作,就能兼容 Honeycomb、Grafana Cloud 和 Axiom 等常用可观测性平台。如果可观测性提供商提供 OpenTelemetry 端点,你就可以导出跟踪和日志。

你还可以设置 persist: false,将跟踪导出到目标位置,而不在 Cloudflare 仪表板中持久保存。这让第三方可观测性提供商成为跟踪数据的唯一存储位置。

有关从 Workers 导出 OpenTelemetry 数据的方法,请参阅 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 跟踪数据保留七天。从 2026 年 12 月 1 日起,已存储的跟踪数据将按照 Cloudflare Observability 定价计入账户级摄取和存储用量。

抽样会减少摄取和存储的 span 数量,从而降低计费用量。

这篇文档对您有帮助吗?