Cloudflare Workers 自动追踪兼容性标志Automatic tracing完全指南从 Wrangler 配置到 OpenTelemetry 导出【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本指南以 cloudflare-docs 仓库中的 automatic-tracing.md 兼容性标志文档为骨架完整讲解enable_workers_observability_tracing标志的作用、两种启用方式、observability配置项的细节并结合 Workers Traces 文档 与相关变更记录带你掌握在无需修改任何业务代码的前提下为 Worker 一键开启端到端请求追踪的实战方法。什么是 Automatic tracing 兼容性标志Cloudflare Workers 通过兼容性标志Compatibility Flags机制来平滑地引入行为变更新行为默认不生效用户显式开启对应标志后即可提前体验或保持旧行为不变以维护现有应用的稳定性。该机制在仓库中由 compatibility-flags.ts 的compatibilityFlagsSchema定义其中enable_flag字段声明了开启某个行为所需的标志名。Automatic tracing自动追踪正是这一机制下的一个标志定义于 src/content/compatibility-flags/automatic-tracing.md其关键元数据为标志名enable_flagenable_workers_observability_tracing生效排序日期sort_date2025-11-05该标志的作用非常聚焦在 Wrangler 配置文件中声明observability.enabled true时默认启用 Workers Tracing即自动追踪。在兼容性日期早于该标志、或未开启该标志的 Worker 上observability.enabled只负责开启可观测性整体开关并不会自动产生追踪数据——你需要显式声明追踪子配置。时间线上的一致性佐证仓库变更记录 2025-11-07-automatic-tracing.mdx 宣布Workers automatic tracing 进入开放 Beta并提供了与此兼容性标志配套的配置示例。两种开启自动追踪的方式原文档明确给出了两条等价路径以下是完整原样继承并补充说明。方式一开启兼容性标志推荐用于新部署在wrangler.toml或wrangler.jsonc中设置{ observability: { enabled: true } }只要你的 Worker 配置了enable_workers_observability_tracing兼容性标志同时满足上述observability.enabled trueCloudflare 就会自动开始为你的 Worker 记录追踪数据无需安装 SDK也无需改动任何代码。注意兼容性标志通常通过 Wrangler 的compatibility_flags数组或compatibility_date隐式引入。由于本标志的sort_date为 2025-11-05若你的 Worker 使用的compatibility_date等于或晚于该日期则此行为默认开启若早于该日期则需要显式添加该标志。方式二显式开启追踪子配置无需标志、兼容旧日期如果你希望不依赖兼容性标志即使在较旧的compatibility_date下也能显式打开自动追踪可以在 Wrangler 配置中直接声明{ observability: { traces: { enabled: true } } }这是方式一的显式等价写法observability.traces.enabled true可以独立于兼容性标志生效是面向旧兼容日期环境下的标准做法。深入解析 Wrangler 的 observability 配置在 Workers Traces 文档 的 How to enable tracing 一节中给出了更完整的生产级配置形态可与上面的两种方式相互印证{ observability: { traces: { enabled: true, // 可选采样率推荐高流量工作负载设置 head_sampling_rate: 0.05 } } }各字段含义如下字段类型说明observability.enabledboolean可观测性总开关配合自动追踪兼容性标志时为true即默认开启追踪observability.traces.enabledboolean显式开启追踪的独立开关不依赖兼容性标志observability.traces.head_sampling_ratenumber追踪采样率取值范围01默认1即 100% 请求被追踪observability.logs.enabledboolean日志开关与追踪独立控制observability.logs.head_sampling_ratenumber日志采样率可与追踪采样率分别设置若你不指定head_sampling_rate默认值为1意味着开启追踪后全部请求都会被记录——对于高流量 Worker建议显式设置采样率如0.05表示 100 个请求中记录约 5 个以控制存储量与成本。采样属于 head-based sampling 机制未被采样的请求不会产生任何追踪开销。依据说明上述默认值、取值范围与 head-based 说明均来自 traces/index.mdx 的 Sampling 一节属仓库可确认的事实。自动追踪究竟记录了什么开启后Cloudflare 会在 Worker 运行时自动埋点out of the box不需要任何代码改动或 SDK。根据 traces/index.mdx 的 Automatic instrumentation 一节被自动记录的操作包括Fetch 调用所有出站 HTTP 请求记录时序、状态码与请求元数据用于定位外部依赖对应用性能的影响Binding 调用Worker 各类 Binding 的交互例如 KV 的读/写、R2 对象存储操作、Durable Object 调用Handler 调用每次 Worker 调用的完整生命周期覆盖 fetch 处理器、scheduled 处理器、queue 消费者 等触发类型。完整的被埋点操作清单见 spans-and-attributes。此外你还可以通过 自定义 spans 为应用自身逻辑增加埋点自定义 span 会自动嵌套在平台内置埋点之下形成覆盖平台操作与自有代码的端到端视图。跨子请求的统一追踪仓库变更记录 2026-05-07-automatic-tracing-across-do-and-worker-subrequests.mdx 进一步指出追踪上下文现在可以自动跨越 Worker-to-Worker 子请求传播通过 service bindings 或 Durable Object 发起的调用会产生单条统一 trace而不是多条互不相连的 trace。这意味着你可以在一个 trace 视图中跟随请求穿过整个 Worker 架构并将服务绑定与 Durable Object 调用视为嵌套子 span从而在 Cloudflare 仪表盘或外部可观测平台中调试跨 Worker 的请求链路。导出追踪数据到第三方平台OpenTelemetryWorkers Tracing 遵循 OpenTelemetryOTel标准可零成本地与 Honeycomb、Grafana Cloud、Axiom 等主流可观测平台对接。只要你的观测平台提供 OpenTelemetry endpoint即可导出 traces以及相关联的 logs。参见 导出 OpenTelemetry 数据。若你希望第三方平台成为唯一 trace 存储地可以设置persist: false将 trace 导出到目标平台的同时不在 Cloudflare 仪表盘持久化。需要特别留意的是根据 known-limitations.md当前导出到外部平台时trace ID 不会传播到 Cloudflare 之外的服务即 Worker 的 trace 不会与你在可观测工具中其他非 Cloudflare 服务的 trace 关联起来团队正在基于 W3C Trace Context 标准 推进外部上下文传播。已知限制与注意事项Beta 阶段根据 known-limitations.md当前处于开放 Beta 的 Workers tracing 有以下限制值得了解非 I/O 操作可能显示 0 ms由于 Workers Runtime 为防 Spectre 攻击而采取的安全措施运行时仅在 I/O 事件发生时更新时间因此部分 span 即使实际耗时更长也可能显示0 ms外部 trace 上下文传播未完成见上文导出场景下 trace 无法与非 Cloudflare 服务关联span 属性尚不完整团队计划为每个 span 增加更多属性span 与属性命名可能变化Beta 期间命名尚未最终确定可能随 OpenTelemetry 语义约定调整建议定期查阅 spans-and-attributes已知问题少数属性只适用于部分 span如service.name、faas.name在跨 trace 与日志按 Worker 名过滤/分组时应统一使用$metadata.servicetrace 进行中时根 span 会显示Trace in Progress需稍候片刻以获取完整 trace。验证与进一步阅读在 cloudflare-docs 仓库中你可以通过以下路径继续深入兼容性标志原文src/content/compatibility-flags/automatic-tracing.md兼容性标志元数据 Schemasrc/schemas/compatibility-flags.tsWorkers Traces 主文档src/content/docs/workers/observability/traces/index.mdx含完整采样配置与计费说明开放 Beta 公告src/content/changelog/workers/2025-11-07-automatic-tracing.mdx跨子请求统一追踪更新src/content/changelog/workers/2026-05-07-automatic-tracing-across-do-and-worker-subrequests.mdx已知限制src/content/docs/workers/observability/traces/known-limitations.md快速上手清单在 Wrangler 配置中写入observability.enabled true并确保 Worker 的compatibility_date不早于2025-11-05或显式添加enable_workers_observability_tracing标志若使用较旧的compatibility_date改为显式设置observability.traces.enabled true高流量 Worker 建议同时配置head_sampling_rate如0.05部署后到 Cloudflare 仪表盘的 Workers Observability 页面查看 trace 瀑布视图如需与自建观测平台打通配置 OTLP 兼容的导出目标并按需设置persist: false。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Workers 自动追踪兼容性标志（Automatic tracing）完全指南：从 Wrangler 配置到 OpenTelemetry 导出
Cloudflare Workers 自动追踪兼容性标志Automatic tracing完全指南从 Wrangler 配置到 OpenTelemetry 导出【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本指南以 cloudflare-docs 仓库中的 automatic-tracing.md 兼容性标志文档为骨架完整讲解enable_workers_observability_tracing标志的作用、两种启用方式、observability配置项的细节并结合 Workers Traces 文档 与相关变更记录带你掌握在无需修改任何业务代码的前提下为 Worker 一键开启端到端请求追踪的实战方法。什么是 Automatic tracing 兼容性标志Cloudflare Workers 通过兼容性标志Compatibility Flags机制来平滑地引入行为变更新行为默认不生效用户显式开启对应标志后即可提前体验或保持旧行为不变以维护现有应用的稳定性。该机制在仓库中由 compatibility-flags.ts 的compatibilityFlagsSchema定义其中enable_flag字段声明了开启某个行为所需的标志名。Automatic tracing自动追踪正是这一机制下的一个标志定义于 src/content/compatibility-flags/automatic-tracing.md其关键元数据为标志名enable_flagenable_workers_observability_tracing生效排序日期sort_date2025-11-05该标志的作用非常聚焦在 Wrangler 配置文件中声明observability.enabled true时默认启用 Workers Tracing即自动追踪。在兼容性日期早于该标志、或未开启该标志的 Worker 上observability.enabled只负责开启可观测性整体开关并不会自动产生追踪数据——你需要显式声明追踪子配置。时间线上的一致性佐证仓库变更记录 2025-11-07-automatic-tracing.mdx 宣布Workers automatic tracing 进入开放 Beta并提供了与此兼容性标志配套的配置示例。两种开启自动追踪的方式原文档明确给出了两条等价路径以下是完整原样继承并补充说明。方式一开启兼容性标志推荐用于新部署在wrangler.toml或wrangler.jsonc中设置{ observability: { enabled: true } }只要你的 Worker 配置了enable_workers_observability_tracing兼容性标志同时满足上述observability.enabled trueCloudflare 就会自动开始为你的 Worker 记录追踪数据无需安装 SDK也无需改动任何代码。注意兼容性标志通常通过 Wrangler 的compatibility_flags数组或compatibility_date隐式引入。由于本标志的sort_date为 2025-11-05若你的 Worker 使用的compatibility_date等于或晚于该日期则此行为默认开启若早于该日期则需要显式添加该标志。方式二显式开启追踪子配置无需标志、兼容旧日期如果你希望不依赖兼容性标志即使在较旧的compatibility_date下也能显式打开自动追踪可以在 Wrangler 配置中直接声明{ observability: { traces: { enabled: true } } }这是方式一的显式等价写法observability.traces.enabled true可以独立于兼容性标志生效是面向旧兼容日期环境下的标准做法。深入解析 Wrangler 的 observability 配置在 Workers Traces 文档 的 How to enable tracing 一节中给出了更完整的生产级配置形态可与上面的两种方式相互印证{ observability: { traces: { enabled: true, // 可选采样率推荐高流量工作负载设置 head_sampling_rate: 0.05 } } }各字段含义如下字段类型说明observability.enabledboolean可观测性总开关配合自动追踪兼容性标志时为true即默认开启追踪observability.traces.enabledboolean显式开启追踪的独立开关不依赖兼容性标志observability.traces.head_sampling_ratenumber追踪采样率取值范围01默认1即 100% 请求被追踪observability.logs.enabledboolean日志开关与追踪独立控制observability.logs.head_sampling_ratenumber日志采样率可与追踪采样率分别设置若你不指定head_sampling_rate默认值为1意味着开启追踪后全部请求都会被记录——对于高流量 Worker建议显式设置采样率如0.05表示 100 个请求中记录约 5 个以控制存储量与成本。采样属于 head-based sampling 机制未被采样的请求不会产生任何追踪开销。依据说明上述默认值、取值范围与 head-based 说明均来自 traces/index.mdx 的 Sampling 一节属仓库可确认的事实。自动追踪究竟记录了什么开启后Cloudflare 会在 Worker 运行时自动埋点out of the box不需要任何代码改动或 SDK。根据 traces/index.mdx 的 Automatic instrumentation 一节被自动记录的操作包括Fetch 调用所有出站 HTTP 请求记录时序、状态码与请求元数据用于定位外部依赖对应用性能的影响Binding 调用Worker 各类 Binding 的交互例如 KV 的读/写、R2 对象存储操作、Durable Object 调用Handler 调用每次 Worker 调用的完整生命周期覆盖 fetch 处理器、scheduled 处理器、queue 消费者 等触发类型。完整的被埋点操作清单见 spans-and-attributes。此外你还可以通过 自定义 spans 为应用自身逻辑增加埋点自定义 span 会自动嵌套在平台内置埋点之下形成覆盖平台操作与自有代码的端到端视图。跨子请求的统一追踪仓库变更记录 2026-05-07-automatic-tracing-across-do-and-worker-subrequests.mdx 进一步指出追踪上下文现在可以自动跨越 Worker-to-Worker 子请求传播通过 service bindings 或 Durable Object 发起的调用会产生单条统一 trace而不是多条互不相连的 trace。这意味着你可以在一个 trace 视图中跟随请求穿过整个 Worker 架构并将服务绑定与 Durable Object 调用视为嵌套子 span从而在 Cloudflare 仪表盘或外部可观测平台中调试跨 Worker 的请求链路。导出追踪数据到第三方平台OpenTelemetryWorkers Tracing 遵循 OpenTelemetryOTel标准可零成本地与 Honeycomb、Grafana Cloud、Axiom 等主流可观测平台对接。只要你的观测平台提供 OpenTelemetry endpoint即可导出 traces以及相关联的 logs。参见 导出 OpenTelemetry 数据。若你希望第三方平台成为唯一 trace 存储地可以设置persist: false将 trace 导出到目标平台的同时不在 Cloudflare 仪表盘持久化。需要特别留意的是根据 known-limitations.md当前导出到外部平台时trace ID 不会传播到 Cloudflare 之外的服务即 Worker 的 trace 不会与你在可观测工具中其他非 Cloudflare 服务的 trace 关联起来团队正在基于 W3C Trace Context 标准 推进外部上下文传播。已知限制与注意事项Beta 阶段根据 known-limitations.md当前处于开放 Beta 的 Workers tracing 有以下限制值得了解非 I/O 操作可能显示 0 ms由于 Workers Runtime 为防 Spectre 攻击而采取的安全措施运行时仅在 I/O 事件发生时更新时间因此部分 span 即使实际耗时更长也可能显示0 ms外部 trace 上下文传播未完成见上文导出场景下 trace 无法与非 Cloudflare 服务关联span 属性尚不完整团队计划为每个 span 增加更多属性span 与属性命名可能变化Beta 期间命名尚未最终确定可能随 OpenTelemetry 语义约定调整建议定期查阅 spans-and-attributes已知问题少数属性只适用于部分 span如service.name、faas.name在跨 trace 与日志按 Worker 名过滤/分组时应统一使用$metadata.servicetrace 进行中时根 span 会显示Trace in Progress需稍候片刻以获取完整 trace。验证与进一步阅读在 cloudflare-docs 仓库中你可以通过以下路径继续深入兼容性标志原文src/content/compatibility-flags/automatic-tracing.md兼容性标志元数据 Schemasrc/schemas/compatibility-flags.tsWorkers Traces 主文档src/content/docs/workers/observability/traces/index.mdx含完整采样配置与计费说明开放 Beta 公告src/content/changelog/workers/2025-11-07-automatic-tracing.mdx跨子请求统一追踪更新src/content/changelog/workers/2026-05-07-automatic-tracing-across-do-and-worker-subrequests.mdx已知限制src/content/docs/workers/observability/traces/known-limitations.md快速上手清单在 Wrangler 配置中写入observability.enabled true并确保 Worker 的compatibility_date不早于2025-11-05或显式添加enable_workers_observability_tracing标志若使用较旧的compatibility_date改为显式设置observability.traces.enabled true高流量 Worker 建议同时配置head_sampling_rate如0.05部署后到 Cloudflare 仪表盘的 Workers Observability 页面查看 trace 瀑布视图如需与自建观测平台打通配置 OTLP 兼容的导出目标并按需设置persist: false。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考