Envoy 分布式链路追踪架构解析从 x-request-id 采样到 Tracer 插件实现【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoyEnvoy 通过三类能力支撑服务网格中的分布式追踪UUID 请求 ID 生成与稳定采样、客户端 Trace ID 关联joining、以及可插拔的外部 Tracer 集成Zipkin、Datadog、Jaeger、OpenTelemetry、SkyWalking、X-Ray、Fluentd 等。本篇基于仓库中的追踪概览文档与对应源码完整拆解 Envoy 如何发起一条 trace、如何在调用链中传播 trace context以及 sidecar 与 gateway 两种部署模式下 CLIENT/SERVER span 的正确生成方式帮助你在生产中正确配置追踪采集并诊断跨服务延迟。一、Envoy 追踪体系概览分布式追踪让开发者能够可视化大型服务架构中的调用流对理解序列化开销、并行度与延迟来源非常关键。Envoy 在追踪方面提供三项基础能力请求 ID 生成Envoy 在需要时生成 UUID 并填充到x-request-idHTTP 头中。应用可以转发该头用于统一日志与追踪。该行为可通过HttpConnectionManager的request_id_extension字段按连接管理器粒度配置。客户端 Trace ID 关联x-client-trace-id头用于将外部不可信的请求 ID 与内部可信的x-request-id关联起来。外部追踪服务集成Envoy 支持可插拔的外部 trace 可视化提供方分两个子类内置于 Envoy 代码库的追踪器Zipkin、Jaeger、Datadog、SkyWalking、AWS X-Ray、Fluentd以第三方插件形式提供的追踪器例如 Instana。从源码结构看内置追踪器统一实现在source/extensions/tracers/目录下每个 tracer 一个子包datadog、opentelemetry、skywalking、xray、zipkin、fluentd以及 dynamic_modules 动态模块。各 tracer 通过公共基类 FactoryBase 完成工厂注册该模板类继承Server::Configuration::TracerFactory自动处理配置 proto 的向下转型与校验MessageUtil::downcastAndValidate子类只需实现createTracerDriverTyped即可产出Tracing::Driver实例——这正是“可插拔”的落地机制。二、如何发起一条 Trace处理请求的 HTTP 连接管理器必须配置了HttpConnectionManager.Tracing对象后追踪才可能被触发。文档指出三种发起方式外部客户端通过x-client-trace-id头发起内部服务通过x-envoy-force-trace头强制发起通过random_sampling运行时参数随机采样发起。发起结果即“trace reason”最终会被记录进请求 ID 本身。这一点在 UuidRequestIdConfig proto 中有明确定义默认 UUID 实现的x-request-id是 UUID4其第 13 个 nibble 按标准固定为4Envoy 将该 nibble 改写为不同的值来承载采样决策——9被采样a服务端强制追踪b客户端 ID 关联触发的追踪4未采样默认。这一设计在 UUIDRequestIDExtension 实现 中可以直接看到源码注释将常量解释得很清楚TRACE_SAMPLED 9、TRACE_FORCED a、TRACE_CLIENT b、NO_TRACE 4修改位置由TRACE_BYTE_POSITION 14指定。这个“把采样决策打进请求 ID”的机制带来了重要收益同一请求 ID 在一整支 Envoy 舰队fleet中的采样决策是稳定一致的边缘与侧车 Envoy 不会因为各自独立抛硬币而把一条 trace 采样成碎片。三、Trace Context 跨服务传播Envoy 只能报告代理之间通信的追踪信息。要把调用流中各代理产生的追踪片段关联起来服务本身必须在入站请求与出站请求之间传播特定的 trace context。3.1 x-request-id 必须传播无论使用哪个追踪提供方服务都应传播x-request-id以让被调用各服务的日志可以相互关联。Envoy 的请求 ID 实现是可扩展的默认采用UuidRequestIdConfig实现配置写在 HCM 的request_id_extension字段中。两个关键配置项在 proto 定义 与 实现 中均有体现pack_trace_reason默认 true控制是否修改请求 ID 的 UUID4 以打包最终 trace reason。禁用后依赖外部生成且必须保持不变的请求 ID 就不会被破坏但代价是失去 stable sampling 与 trace reason 稳定传播等能力——“禁用后 trace、访问日志等的稳定采样将不再工作只剩随机采样”。use_request_id_for_trace_sampling默认 true控制 Envoy 的采样策略是否由x-request-id的值决定。若舰队中混入了非 Envoy 的服务代理Envoy 的采样策略不会考虑那个代理的采样策略在多种服务代理混布的场景下更有效的做法是绕过 Envoy 的采样策略、按 trace 提供方自身的采样策略采样即将该字段设为false。3.2 各 Tracer 要求的附加上下文要建立 span逻辑工作单元之间的父子关系各追踪提供方还需要额外的上下文。可以在服务内直接使用 LightStep经由 OpenTelemetry API或 Zipkin tracer 从入站请求提取 trace context 并注入到后续出站请求这样服务还能创建描述内部工作的附加 span。也可以由服务手动传播 trace context各提供方所需的头不同Tracer需服务传播的 HTTP 头LightStepOpenTelemetry 兼容x-ot-span-contextZipkinB3 头x-b3-traceid、x-b3-spanid、x-b3-parentspanid、x-b3-sampled、x-b3-flags另支持更紧凑的单头格式b3Datadogx-datadog-trace-id、x-datadog-parent-id、x-datadog-sampling-prioritySkyWalkingsw8AWS X-Rayx-amzn-trace-id其中 Zipkin 的x-b3-sampled头也可以由外部客户端提供用于对特定请求开启或关闭追踪。3.3 Zipkin 的 B3 与 W3C 双格式支持Zipkin tracer 可配置为同时支持 B3 与 W3C trace context 两种格式以提升互操作性由 ZipkinConfig 的trace_context_option字段控制设为USE_B3_WITH_W3C_PROPAGATION时对下游请求优先从 B3 头提取 trace contextB3 头不存在时回退到 W3C 追踪头traceparent与tracestate对上游请求同时注入 B3 与 W3C 追踪头最大化兼容性。默认值为USE_B3proto 注释说明这是为保持向后兼容而保留仅使用 B3 头完成提取与注入。该枚举在 proto 中定义如下zipkin.protoenum TraceContextOption { // Use B3 headers only (default behavior). USE_B3 0; // Enable B3 and W3C dual header support: // - For downstream: Extract from B3 headers first, fallback to W3C traceparent if B3 is unavailable. // - For upstream: Inject both B3 and W3C traceparent headers. USE_B3_WITH_W3C_PROPAGATION 1; }Zipkin tracer 的上下文提取逻辑位于 span_context_extractor与 zipkin_tracer_impl.cc 共同完成 B3/W3C 头的解析与注入。四、每条 Trace 包含哪些数据一条端到端 trace 由一个或多个 span 组成。span 表示有开始时间、持续时间并可携带元数据的逻辑工作单元。Envoy 为每个 span 生成的数据包括源服务集群通过--service-cluster设置请求的开始时间与持续时间源主机通过--service-node设置下游集群通过downstream-service-cluster头设置HTTP 请求的 URL、方法、协议与 user-agent通过Tracing.custom_tags设置的自定义标签上游集群名、可观测性名与地址HTTP 响应状态码GRPC 响应状态与消息如有当 HTTP 状态为 5xx 或 GRPC 状态非 OK 且表示服务端错误时附加的错误标签各追踪系统自身的特定元数据。span 还有一个名称operation默认是被调用服务的主机名可以通过路由上的config.route.v3.Decorator自定义也可以用x-envoy-decorator-operation头覆盖。Envoy 会自动把 span 发送到追踪采集器。不同采集器用公共信息把多个 span 拼接成一条 traceLightStep 用全局唯一的x-request-idZipkin 与 Datadog 用 trace ID 配置。具体配置方式参见envoy.config.trace.v3.Tracing的 v3 API 参考。五、Baggage贯穿整条 Trace 的数据通道Baggage 提供了一种机制使数据在整个 trace 生命周期内可用。与标签tags通常带外out-of-band发送给采集器不同baggage 数据被直接注入实际请求上下文在整个请求期间对应用可见。这让元数据可以从请求起点透明地流经整个网格而不依赖应用特定的传播改造。各追踪提供方对 baggage 读写的支持程度不一LightStep以及任何 OpenTelemetry 兼容的 tracer可读写 baggageZipkin尚未实现支持X-Ray 与 Fluentd不支持 baggage。值得注意的是仓库中 OpenTelemetry tracer 的实现opentelemetry_tracer_impl.cc 等基于 OpenTelemetry C SDK其 span context 提取逻辑在 span_context_extractor.cc是 OpenTelemetry 兼容路径的落地位置。六、Span 类型与 Envoy 的两种工作模式SkyWalking、Zipkin、OpenTelemetry 等追踪系统都提供 CLIENT 与 SERVER 两类最常见的 span 类型CLIENT span 由发送请求的客户端生成SERVER span 由接收请求的服务端生成。基本的 trace 链形如- [SERVER - CLIENT] - [SERVER - CLIENT] - ... App A App B链上每一跳都必须保证 span 类型正确server span 的父 span 通常应是 client span。6.1 模式一Sidecar 作为单一跳当 Envoy 以 sidecar 形式广泛部署于服务网格时sidecar 与其关联的应用被视为 trace 链上的单一跳。理想链路为- [[SERVER (inbound sidecar) - App - CLIENT (outbound sidecar)]] - ... App入站 sidecar 总是生成 SERVER span出站 sidecar 总是生成 CLIENT span应用自身不生成 span只负责传播 trace context。6.2 模式二Gateway / 独立跳模式当 Envoy 用作 gateway或 sidecar 与应用被视为 trace 链上的独立跳时链路变为- [SERVER - CLIENT] - [SERVER - CLIENT] - [SERVER - CLIENT] - [SERVER - CLIENT] - ... Gateway Inbound Sidecar App Outbound SidecarEnvoy 为下游请求生成 SERVER span为上游请求生成 CLIENT span应用也可以为自己的工作生成 span。要启用该模式需显式将HttpConnectionManager.Tracing的spawn_upstream_span字段设为true指示追踪提供方为上游请求生成 CLIENT span、把 Envoy 当作独立跳处理。该字段定义在 http_connection_manager.proto 的Tracing消息中google.protobuf.BoolValue spawn_upstream_span 10;。从相关配置演进看Zipkin 早期的split_spans_for_request与 router 的start_child_span已被spawn_upstream_span取代见 ZipkinConfig 中的弃用说明新配置应直接使用spawn_upstream_span来控制 span 的生成。七、参考路径小结追踪架构文档tracing.rst同目录观测性文档access_logging.rst、statistics.rstUUID 请求 ID 配置与实现uuid.proto、uuid/config.hZipkin 配置含 B3/W3C 选项zipkin.protoTracer 工厂注册基类factory_base.h各内置追踪器实现source/extensions/tracers/掌握以上内容后你可以按部署形态sidecar 单跳或 gateway 独立跳正确选择spawn_upstream_span等配置保证 trace 链中 span 类型与父子关系正确并能根据混合代理舰队、baggage 需求与 W3C 互操作要求挑选合适的pack_trace_reason、use_request_id_for_trace_sampling与trace_context_option组合让 Envoy 采集到的 trace 数据与业务日志、其他服务代理的采样策略真正对齐。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Envoy 分布式链路追踪架构解析：从 x-request-id 采样到 Tracer 插件实现
Envoy 分布式链路追踪架构解析从 x-request-id 采样到 Tracer 插件实现【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoyEnvoy 通过三类能力支撑服务网格中的分布式追踪UUID 请求 ID 生成与稳定采样、客户端 Trace ID 关联joining、以及可插拔的外部 Tracer 集成Zipkin、Datadog、Jaeger、OpenTelemetry、SkyWalking、X-Ray、Fluentd 等。本篇基于仓库中的追踪概览文档与对应源码完整拆解 Envoy 如何发起一条 trace、如何在调用链中传播 trace context以及 sidecar 与 gateway 两种部署模式下 CLIENT/SERVER span 的正确生成方式帮助你在生产中正确配置追踪采集并诊断跨服务延迟。一、Envoy 追踪体系概览分布式追踪让开发者能够可视化大型服务架构中的调用流对理解序列化开销、并行度与延迟来源非常关键。Envoy 在追踪方面提供三项基础能力请求 ID 生成Envoy 在需要时生成 UUID 并填充到x-request-idHTTP 头中。应用可以转发该头用于统一日志与追踪。该行为可通过HttpConnectionManager的request_id_extension字段按连接管理器粒度配置。客户端 Trace ID 关联x-client-trace-id头用于将外部不可信的请求 ID 与内部可信的x-request-id关联起来。外部追踪服务集成Envoy 支持可插拔的外部 trace 可视化提供方分两个子类内置于 Envoy 代码库的追踪器Zipkin、Jaeger、Datadog、SkyWalking、AWS X-Ray、Fluentd以第三方插件形式提供的追踪器例如 Instana。从源码结构看内置追踪器统一实现在source/extensions/tracers/目录下每个 tracer 一个子包datadog、opentelemetry、skywalking、xray、zipkin、fluentd以及 dynamic_modules 动态模块。各 tracer 通过公共基类 FactoryBase 完成工厂注册该模板类继承Server::Configuration::TracerFactory自动处理配置 proto 的向下转型与校验MessageUtil::downcastAndValidate子类只需实现createTracerDriverTyped即可产出Tracing::Driver实例——这正是“可插拔”的落地机制。二、如何发起一条 Trace处理请求的 HTTP 连接管理器必须配置了HttpConnectionManager.Tracing对象后追踪才可能被触发。文档指出三种发起方式外部客户端通过x-client-trace-id头发起内部服务通过x-envoy-force-trace头强制发起通过random_sampling运行时参数随机采样发起。发起结果即“trace reason”最终会被记录进请求 ID 本身。这一点在 UuidRequestIdConfig proto 中有明确定义默认 UUID 实现的x-request-id是 UUID4其第 13 个 nibble 按标准固定为4Envoy 将该 nibble 改写为不同的值来承载采样决策——9被采样a服务端强制追踪b客户端 ID 关联触发的追踪4未采样默认。这一设计在 UUIDRequestIDExtension 实现 中可以直接看到源码注释将常量解释得很清楚TRACE_SAMPLED 9、TRACE_FORCED a、TRACE_CLIENT b、NO_TRACE 4修改位置由TRACE_BYTE_POSITION 14指定。这个“把采样决策打进请求 ID”的机制带来了重要收益同一请求 ID 在一整支 Envoy 舰队fleet中的采样决策是稳定一致的边缘与侧车 Envoy 不会因为各自独立抛硬币而把一条 trace 采样成碎片。三、Trace Context 跨服务传播Envoy 只能报告代理之间通信的追踪信息。要把调用流中各代理产生的追踪片段关联起来服务本身必须在入站请求与出站请求之间传播特定的 trace context。3.1 x-request-id 必须传播无论使用哪个追踪提供方服务都应传播x-request-id以让被调用各服务的日志可以相互关联。Envoy 的请求 ID 实现是可扩展的默认采用UuidRequestIdConfig实现配置写在 HCM 的request_id_extension字段中。两个关键配置项在 proto 定义 与 实现 中均有体现pack_trace_reason默认 true控制是否修改请求 ID 的 UUID4 以打包最终 trace reason。禁用后依赖外部生成且必须保持不变的请求 ID 就不会被破坏但代价是失去 stable sampling 与 trace reason 稳定传播等能力——“禁用后 trace、访问日志等的稳定采样将不再工作只剩随机采样”。use_request_id_for_trace_sampling默认 true控制 Envoy 的采样策略是否由x-request-id的值决定。若舰队中混入了非 Envoy 的服务代理Envoy 的采样策略不会考虑那个代理的采样策略在多种服务代理混布的场景下更有效的做法是绕过 Envoy 的采样策略、按 trace 提供方自身的采样策略采样即将该字段设为false。3.2 各 Tracer 要求的附加上下文要建立 span逻辑工作单元之间的父子关系各追踪提供方还需要额外的上下文。可以在服务内直接使用 LightStep经由 OpenTelemetry API或 Zipkin tracer 从入站请求提取 trace context 并注入到后续出站请求这样服务还能创建描述内部工作的附加 span。也可以由服务手动传播 trace context各提供方所需的头不同Tracer需服务传播的 HTTP 头LightStepOpenTelemetry 兼容x-ot-span-contextZipkinB3 头x-b3-traceid、x-b3-spanid、x-b3-parentspanid、x-b3-sampled、x-b3-flags另支持更紧凑的单头格式b3Datadogx-datadog-trace-id、x-datadog-parent-id、x-datadog-sampling-prioritySkyWalkingsw8AWS X-Rayx-amzn-trace-id其中 Zipkin 的x-b3-sampled头也可以由外部客户端提供用于对特定请求开启或关闭追踪。3.3 Zipkin 的 B3 与 W3C 双格式支持Zipkin tracer 可配置为同时支持 B3 与 W3C trace context 两种格式以提升互操作性由 ZipkinConfig 的trace_context_option字段控制设为USE_B3_WITH_W3C_PROPAGATION时对下游请求优先从 B3 头提取 trace contextB3 头不存在时回退到 W3C 追踪头traceparent与tracestate对上游请求同时注入 B3 与 W3C 追踪头最大化兼容性。默认值为USE_B3proto 注释说明这是为保持向后兼容而保留仅使用 B3 头完成提取与注入。该枚举在 proto 中定义如下zipkin.protoenum TraceContextOption { // Use B3 headers only (default behavior). USE_B3 0; // Enable B3 and W3C dual header support: // - For downstream: Extract from B3 headers first, fallback to W3C traceparent if B3 is unavailable. // - For upstream: Inject both B3 and W3C traceparent headers. USE_B3_WITH_W3C_PROPAGATION 1; }Zipkin tracer 的上下文提取逻辑位于 span_context_extractor与 zipkin_tracer_impl.cc 共同完成 B3/W3C 头的解析与注入。四、每条 Trace 包含哪些数据一条端到端 trace 由一个或多个 span 组成。span 表示有开始时间、持续时间并可携带元数据的逻辑工作单元。Envoy 为每个 span 生成的数据包括源服务集群通过--service-cluster设置请求的开始时间与持续时间源主机通过--service-node设置下游集群通过downstream-service-cluster头设置HTTP 请求的 URL、方法、协议与 user-agent通过Tracing.custom_tags设置的自定义标签上游集群名、可观测性名与地址HTTP 响应状态码GRPC 响应状态与消息如有当 HTTP 状态为 5xx 或 GRPC 状态非 OK 且表示服务端错误时附加的错误标签各追踪系统自身的特定元数据。span 还有一个名称operation默认是被调用服务的主机名可以通过路由上的config.route.v3.Decorator自定义也可以用x-envoy-decorator-operation头覆盖。Envoy 会自动把 span 发送到追踪采集器。不同采集器用公共信息把多个 span 拼接成一条 traceLightStep 用全局唯一的x-request-idZipkin 与 Datadog 用 trace ID 配置。具体配置方式参见envoy.config.trace.v3.Tracing的 v3 API 参考。五、Baggage贯穿整条 Trace 的数据通道Baggage 提供了一种机制使数据在整个 trace 生命周期内可用。与标签tags通常带外out-of-band发送给采集器不同baggage 数据被直接注入实际请求上下文在整个请求期间对应用可见。这让元数据可以从请求起点透明地流经整个网格而不依赖应用特定的传播改造。各追踪提供方对 baggage 读写的支持程度不一LightStep以及任何 OpenTelemetry 兼容的 tracer可读写 baggageZipkin尚未实现支持X-Ray 与 Fluentd不支持 baggage。值得注意的是仓库中 OpenTelemetry tracer 的实现opentelemetry_tracer_impl.cc 等基于 OpenTelemetry C SDK其 span context 提取逻辑在 span_context_extractor.cc是 OpenTelemetry 兼容路径的落地位置。六、Span 类型与 Envoy 的两种工作模式SkyWalking、Zipkin、OpenTelemetry 等追踪系统都提供 CLIENT 与 SERVER 两类最常见的 span 类型CLIENT span 由发送请求的客户端生成SERVER span 由接收请求的服务端生成。基本的 trace 链形如- [SERVER - CLIENT] - [SERVER - CLIENT] - ... App A App B链上每一跳都必须保证 span 类型正确server span 的父 span 通常应是 client span。6.1 模式一Sidecar 作为单一跳当 Envoy 以 sidecar 形式广泛部署于服务网格时sidecar 与其关联的应用被视为 trace 链上的单一跳。理想链路为- [[SERVER (inbound sidecar) - App - CLIENT (outbound sidecar)]] - ... App入站 sidecar 总是生成 SERVER span出站 sidecar 总是生成 CLIENT span应用自身不生成 span只负责传播 trace context。6.2 模式二Gateway / 独立跳模式当 Envoy 用作 gateway或 sidecar 与应用被视为 trace 链上的独立跳时链路变为- [SERVER - CLIENT] - [SERVER - CLIENT] - [SERVER - CLIENT] - [SERVER - CLIENT] - ... Gateway Inbound Sidecar App Outbound SidecarEnvoy 为下游请求生成 SERVER span为上游请求生成 CLIENT span应用也可以为自己的工作生成 span。要启用该模式需显式将HttpConnectionManager.Tracing的spawn_upstream_span字段设为true指示追踪提供方为上游请求生成 CLIENT span、把 Envoy 当作独立跳处理。该字段定义在 http_connection_manager.proto 的Tracing消息中google.protobuf.BoolValue spawn_upstream_span 10;。从相关配置演进看Zipkin 早期的split_spans_for_request与 router 的start_child_span已被spawn_upstream_span取代见 ZipkinConfig 中的弃用说明新配置应直接使用spawn_upstream_span来控制 span 的生成。七、参考路径小结追踪架构文档tracing.rst同目录观测性文档access_logging.rst、statistics.rstUUID 请求 ID 配置与实现uuid.proto、uuid/config.hZipkin 配置含 B3/W3C 选项zipkin.protoTracer 工厂注册基类factory_base.h各内置追踪器实现source/extensions/tracers/掌握以上内容后你可以按部署形态sidecar 单跳或 gateway 独立跳正确选择spawn_upstream_span等配置保证 trace 链中 span 类型与父子关系正确并能根据混合代理舰队、baggage 需求与 W3C 互操作要求挑选合适的pack_trace_reason、use_request_id_for_trace_sampling与trace_context_option组合让 Envoy 采集到的 trace 数据与业务日志、其他服务代理的采样策略真正对齐。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考