追踪可让您端到端地了解请求在 Workers 应用程序及关联服务中的完整生命周期。这有助于识别性能瓶颈、调试问题并理解复杂的请求流程。通过追踪,您可以回答以下问题:
- 长时间运行的请求原因是什么?
- Worker 发出的子请求需要多长时间?
- 对 KV Namespace 或 R2 bucket 的调用需要多长时间?
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。
通过在 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.05Workers 跟踪遵循 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 数量,从而降低计费用量。