后端RPC框架【免费下载链接】finagleA fault tolerant, protocol-agnostic RPC system项目地址https://gitcode.com/gh_mirrors/fi/finagle点击查看免费下载Finagle 会为每一个 RPC 请求生成分布式追踪distributed trace数据帮助开发者理解、调试分布式系统在时间与因果上的全貌。本文以 Finagle 的 Tracing 机制为主线从 Trace/Span 的核心模型、Tracer接口与默认加载机制到TraceAPI 的自定义注解、采样Sampling、标准与二进制注解的完整清单逐层展开并结合 finagle-core 与 finagle-zipkin 系列的源码实现给出底层印证。读完本文你将能够配置并替换 Finagle 客户端/服务端的 Tracer编写自定义 Filter 向当前 Trace 写入业务注解利用局部 Span 与计时能力做进程内性能剖析并读懂每一条标准注解由哪个 Filter 在什么位置产生。分布式追踪的核心模型Trace、Span 与 TraceIdFinagle 将一次请求/响应路径上的各个片段表示为Span跨度。一条完整的Trace追踪由一系列因果相关的 Span 组成当客户端发起请求、服务端接收请求、中间经过多个跳hop时每一跳都会产生自己的 Span。关键点在于同一个 Trace 中的所有 Span 共享同一个 64 位traceId这使得 Zipkin 等追踪系统能够按 traceId 把分散在各服务的 Span 重新聚合、排序并还原为一条完整调用链同样在客户端与服务端之间Span id 也是共享的客户端产生的 Span 与服务端产生的对应 Span 通过共同的 id 关联起来。从源码看TraceId本质上是三元组的组合TraceId.scalatrace id整个请求所有 Span 共享的公共 idspan id本次请求片段单个 RPC 或进程内活动独有的 idparent id触发当前 Span 的父请求的 id。文档中的示例很好地说明了跨服务传播时的形态TRACE ID SPAN ID PARENT ID SERVICE M e4bbb7c0f6a2ff07.a5f47e9fced314a2:694eb2f05b8fd7d1 | | | ----------------- | | v v SERVICE N e4bbb7c0f6a2ff07.263ed9c65773b08:a5f47e9fced314a2Service M 调用 Service N 时两边的traceId相同e4bbb7c0f6a2ff07而 Service N 的 Span 的 parent id 恰好是 Service M 的 span ida5f47e9fced314a2由此形成父子链。对于请求中第一个 Span其 trace id、span id、parent id 三者相同如34429b04b6bbf478.34429b04b6bbf478:34429b04b6bbf478。关于 id 的更多细节SpanId是对Long的封装其字符串形式为无符号 64 位十六进制SpanId.scalaTraceId支持可选的高 64 位traceIdHigh从而兼容 128 位 trace id。在 Trace.scala 中有一个全局 flagobject traceId128Bit extends GlobalFlagBoolean. )即通过-com.twitter.finagle.tracing.traceId128Bittrue可让新的根 Span 使用 128 位 trace id默认 64 位。TraceId.serialize的线上格式为大端序spanId:8 parentId:8 traceId:8 flags:8 (traceIdHigh:8)共 32 字节64 位或 40 字节128 位。追踪数据本身以Record为单位每条Record包含traceId、事件发生时间timestamp、annotation以及可选的durationRecord.scala。这些 Record 在请求路径的每一跳被收集并发送到存储端。追踪系统的配置默认 Tracer 与 ServiceLoader 加载机制Finagle 默认使用DefaultTracerDefaultTracer.scala。它的工作方式是借助 Java 的ServiceLoader从 classpath 中所有已包含的 artifact 里加载Tracer实现并将它们统一包装在一个BroadcastTracer下object DefaultTracer extends Tracer with Proxy { private[this] val tracers LoadService[Tracer]() ... volatile var self: Tracer BroadcastTracer(tracers) ... }也就是说开箱即用只要把finagle-zipkin-scribe包加入 classpath就会自动启用一个通过 Scribe 协议向 Zipkin 发送 Span 的 tracer无需任何代码改动。这也解释了为什么官方文档把添加依赖视为最简单的启用方式。如果你希望全局安装自己的 tracer可以提供一个实现了TracerAPI 的类在 jar 的META-INF/services中按ServiceLoader规范注册该类。Tracer接口Tracer.scala只有两个必须实现的方法外加两个带默认实现的方法record(record: Record): Unit—— 记录一条追踪事件sampleTrace(traceId: TraceId): Option[Boolean]—— 决定是否采样该 traceSome(true)保留、Some(false)丢弃、None表示把决策推迟给下游服务Tracer.SomeTrue/Tracer.SomeFalse是现成的常量getSampleRate: Float—— 采样率0.0~1.0若采样由其他因素决定则返回NaNisActivelyTracing(traceId)默认实现—— 当traceId.sampled为None时返回truetracer 仍活跃但把决策留给子服务为Some(decision)时尊重该决策。此外Tracer还有一个isNull方法默认falseNullTracer会覆盖它为true——这被TraceInitializerFilter等组件用来短路空 tracer避免无谓的上下文切换。在代码中覆盖 TracerBroadcastTracer 实战示例Tracer 不仅可以在全局安装也可以在创建客户端或服务端时指定。文档给出了一个经典示例用BroadcastTracer同时把 trace 发送到 Zipkin经 Scribe和标准输出consoleimport com.twitter.finagle.Http import com.twitter.finagle.tracing.{BroadcastTracer, Record, TraceId, Tracer} import com.twitter.finagle.zipkin.thrift.ZipkinTracer object SystemOutTracer extends Tracer { def record(record: Record): Unit println(record) def sampleTrace(traceId: TraceId): Option[Boolean] Some(false) } val client Http.client .withTracer(BroadcastTracer(Seq( ZipkinTracer.mk(), SystemOutTracer )))注意示例中SystemOutTracer.sampleTrace返回Some(false)表示它自己不做采样决策、仅原样转发记录——采样与否由BroadcastTracer内部的合并逻辑决定。从 BroadcastTracer.scala 的源码可以看到其采样合并规则任何一个子 tracer 返回Some(true)则整体采样所有子 tracer 都返回Some(false)才整体不采样否则返回None把决策留给下游。BroadcastTracer.apply还有优化若过滤掉 null tracer 后只剩 0/1/2/3 个 tracer会分别退化为NullTracer、原 tracer 或专门的Two/Three内部类减少分发开销。关于 NullTracer 的重要警告Finagle 还提供NullTracerNullTracer.scala它丢弃所有 trace 消息。但即使把NullTracer传给withTracerFinagle 客户端仍然会继续向对端传播 trace 信息。这可能导致一个令人惊讶的副作用如果 trace 正在被 Zipkin 之类的分布式追踪服务聚合下游 Span 会因为缺少本端记录而变成孤儿 span。因此官方明确不建议在生产环境使用NullTracer。这从NullTracer的注释也能印证它不会阻止 trace 信息传播到下一跳只会让本主机不记录任何信息。可用 Tracer 一览Finagle 及其生态提供了多种现成的 Tracer 实现按职责分工Tracer说明NullTracer丢弃所有 trace。未配置任何 tracer 时的默认行为BroadcastTracer在过滤后为空时也会退化为它BroadcastTracer把同一条 trace 转发给任意数量的子 tracer适合同时发往多个后端系统。默认情况下所有通过 ServiceLoader 加载的 tracer 都被打包在同一个BroadcastTracer下SamplingTracer只把一部分 trace 转发给底层存储适合请求量高、不想压垮追踪系统的场景。采样决策在新 trace 创建时确定一旦 trace 通过采样该决策会被记录并随 trace 一起传播保证沿途所有 Span 一致通过采样RawZipkinTracer抽象的SamplingTracer负责把 trace 格式化为 Zipkin 可消费的形态但传输层开放给子类实现ScribeZipkinTracer一种RawZipkinTracer用 Scribe 协议把 Span 发送给 Zipkin。随finagle-zipkin-scribeartifact 提供暴露以下配置 flagSamplingTracer的源码SamplingTracer.scala展示了它的双通道过滤record时先经sampler.sampleRecord(record)判断该 record 是否属于被采样 trace只有通过才转交底层 tracersampleTrace时调用sampler.sampleTrace做出决策若 trace 首次被采样还会写入zipkin.sampling_rate二进制注解把采样率固化在 trace 根部这正是文档中Sampling一节所列注解的来源。而ScribeZipkinTracerScribeZipkinTracer.scala的无参构造供 ServiceLoader 使用从全局 flaghost读取 Scribe 地址并配合core.DefaultSampler工作。ScribeZipkinTracer 的配置 flagScribeZipkinTracer暴露两个命令行 flag-com.twitter.finagle.zipkin.hostScribe 服务器地址。定义在 finagle-zipkin-scribe 的 Flags.scala默认值为new InetSocketAddress(localhost, 1463)即本地 1463 端口-com.twitter.finagle.zipkin.initialSampleRate初始采样率。定义在 finagle-zipkin-core 的 Flags.scala类型为Float其Flaggable会校验取值必须在[0.0, 1.0]区间越界会抛出IllegalArgumentException。DefaultSamplerDefaultSampler.scala的逻辑是若用户显式设置了initialSampleRateflag则始终以它为准、不允许代码运行时覆盖否则采用默认采样率并允许运行时通过SamplingTracer.setSampleRate调整。使用 Trace API 添加自定义注解当前活跃 trace 的信息存放在 Finagle 的Context中详见 Contexts.rst而TraceAPITrace.scala是访问与操作当前 trace 的便捷门面它内部通过Contexts.local持有当前Seq[Tracer]通过Contexts.broadcast持有TraceId并支持letId、letTracer、letClear等上下文切换方法。由于每次操作都要做Contexts查找源码注释建议在频繁使用时先通过Trace()捕获一个Tracing实例以批量复用查找结果。最常见的需求是在请求处理过程中记录自定义信息。文档给出了一个在SimpleFilter里记录请求头值的例子import com.twitter.finagle.http.{Request, Response} import com.twitter.finagle.tracing.Trace import com.twitter.finagle.{Service, SimpleFilter} import com.twitter.util.Future class MyFilter extends SimpleFilter[Request, Response] { def apply(request: Request, service: Service[Request, Response]): Future[Response] { val header request.headerMap(Special-Header) Trace.recordBinary(special-header, header) service(request) } }Trace.recordBinary(key, value)写入的是二进制注解binary annotation一个从字符串 key 到二进制 value 的简单映射不携带时间戳。与之相对的是普通注解annotation它描述某个时间点发生的事件并携带时间戳。两类注解的差异决定了它们的用途例如 Client Send 事件发生在某一具体时刻、带时间戳因此可以和 Wire Send 事件做先后排序与耗时对比用于分析请求从客户端代码交到网卡、再到远端服务器的耗时而二进制注解更适合记录请求发生时的系统局部状态例如 GC 当时在做什么。Annotation是密封 ADTAnnotation.scala包含WireSend、ClientSend、ServerRecv、Message、ServiceName、Rpc、ClientAddr、ServerAddr、LocalAddr、BinaryAnnotation(key, value)等变体——上述标准注解表格中的所有条目都能在这个 ADT 中找到对应。另外Trace.scala 还提供了两个进程级全局 flag-com.twitter.finagle.tracing.enabled默认true设为false时关闭本进程所有追踪记录但官方注释明确警告生产环境不建议禁用追踪代码层面也有Trace.enable()/Trace.disable()/Trace.enabled对应的开关。追踪系统的初始化TraceInitializationFilter追踪系统由TraceInitializationFilterTraceInitializationFilter.scala初始化。它存在于 Finagle 默认栈default stack的客户端与服务端两侧且总是位于 Filter 链的最前端即Stack的最里层这样带有 trace 支持的协议可以覆盖 Span 重置逻辑同时仍能在此处被正确上报。该 Filter 的职责是为每个请求建立正确的追踪上下文——要么复用传入的 trace id要么生成一个新的——并在进入服务前把 tracer 压入当前上下文。其apply逻辑结合newId参数区分客户端/服务端为tracer 为 null 时客户端会Trace.letId(Trace.nextId)生成新 id服务端则直接放行非 null 时客户端调用Trace.letTracerAndNextId(tracer)推入 tracer 并生成下一个 TraceId服务端调用Trace.letTracer(tracer)只推入 tracer沿用传入 id若启用了 partitioningfanout true则会用FanoutTracer包裹以便把记录延迟到拿到 peer trace id 后再冲刷保证多分区场景下 trace 不被拆散。客户端与服务端在栈中的装配分别通过TraceInitializerFilter.clientModule与serverModule完成。除此之外AnnotatingTracingFilter是标准注解的通用载体它根据构造参数在服务调用前/后无论成败记录注解并在失败时通过afterFailure回调生成错误注解出于保证注解顺序的目的它用transform而非respond来强制排序否则可能出现 Client Receive 先于 Client Wire Receive 的乱序。围绕它派生了三个标准 FilterServerTracingFilter记录ServerRecv/ServerSend/ServerSendError前缀srvClientTracingFilter记录ClientSend/ClientRecv/ClientRecvError前缀clnt并额外记录finagle.version、finagle.label以及非空的dtab.local/dtab.limited等元数据WireTracingFilter记录传输层事件WireSend/WireRecv/WireRecvError客户端前缀clnt、服务端前缀srv。此外还有ResourceTracingFilter服务端记录srv/finagle_cputime_ns与srv/finagle_continuations_executed资源消耗和TracelessFilter用Trace.letClear清除追踪信息两个辅助组件。局部 Span 与计时剖析进程内行为每个请求都运行在一个 Span 的作用域内该 Span 在请求被接收或初始请求发出时创建。但有时需要把请求处理中的某些阶段拆分成独立事件来分析——这就要用到局部 Spanlocal span它完全存在于单个进程内部适合观察本地计算与外部请求之间的因果关系以及它们彼此的相对时序与耗时。局部 Span 通过Trace#traceLocal创建import com.twitter.finagle.tracing.Trace def chainOfEvents(): Int ??? Trace.traceLocal(important_work) { // perform within the context of a new SpanId chainOfEvents() }代码块会在一个新的 SpanId上下文中执行从而把这段工作从当前 Span 中切分出来。更进一步可以对操作计时并把结果记录进 trace 上下文import com.twitter.finagle.tracing.Trace def complexComputation(): Int ??? val result Trace.time(complexComputation_ns) { // record how long the computation took complexComputation() }Trace.time返回块内计算的结果同时把耗时写入注解。局部 Span 计时的组合使得本地一段计算的性能可以直接与其它分布式计算做横向对比——这正是文档强调的用法理解本地计算与外部请求的相对耗时关系。标准注解Standard Annotations全表Finagle 在请求路径的关键位置自动记录以下标准注解每一类都由对应 Filter 产生Annotation描述产生位置Wire Send消息被交给传输层的时间WireTracingFilterWire Receive传输层收到消息的时间WireTracingFilterWire Receive Error传输层产生的任意错误消息WireTracingFilterClient Send客户端发出请求的时间ClientTracingFilterClient Receive客户端收到响应的时间ClientTracingFilterClient Receive Error客户端栈产生的任意错误ClientTracingFilterServer Send服务端收到请求的时间ServerTracingFilterServer Receive服务端发出响应的时间ServerTracingFilterServer Send Error服务端栈产生的任意错误ServerTracingFilterService Name该 Span 起源处的服务名TraceInitializationFilterRPCRPC 名称与方法由 service/client 自行记录Message信息性消息RetryFilter、TimeoutFilterClient Address请求的来源地址ClientDispatcherServer Address请求的终端地址DestinationTracingLocal AddressSpan 生成处的本地地址DestinationTracing从 TraceInitializerFilter.scala 的源码可以看到这些注解在栈中的真实装配方式ServerTracingFilter/ClientTracingFilter在 tracer 非空时把TracingFilter接入栈WireTracingFilter的客户端模块记录WireSend→WireRecv、服务端模块记录WireRecv→WireSend共同构成客户端 send/receive → 线上 send/receive → 服务端 recv/send的完整时序链。附加二进制注解Additional Binary Annotations详解除标准注解外Finagle 各模块还会写入一批语义明确的二进制注解文档按功能域逐一列出备份请求Backup Requests—— 由BackupRequestFilter产生srv/backup_request_processing服务端处理备份请求时生成clnt/backup_request_threshold_ms配置的备份请求触发阈值毫秒clnt/backup_request_span_id备份请求的 span id用于区分哪些 Span 属于主请求、哪些属于备份请求Client Backup Request IssuedMessage 注解客户端发出备份请求时生成Client Backup Request WonMessage 注解备份请求先于主请求完成时生成Client Backup Request LostMessage 注解备份请求晚于主请求完成时生成。截止时间DeadlinesFinagle 默认只在服务端处理 deadline因此文档只列出srv/前缀注解客户端同样可追踪但默认不产生srv/request_deadlinedeadline 到达的时刻srv/request_deadline_remaining_msdeadline 前剩余毫秒数仅当 deadline 尚未到达时出现srv/request_deadline_exceeded_ms超出 deadline 的毫秒数仅当 deadline 已被超出时出现srv/request_deadline_rejected请求是否因超时被拒绝的布尔值仅当请求被拒绝时出现。垃圾回收Garbage Collection—— 由MkJvmFilter产生GC StartMessage 注解请求前最近一分钟内所有 GC 事件的起始时间戳GC EndMessage 注解请求前最近一分钟内所有 GC 事件的结束时间戳jvm/gc_count请求前最近一分钟内的 GC 次数jvm/gc_ms请求前最近一分钟内花在 GC 上的总时长。载荷大小Payload Size—— 由PayloadSizeFilter产生clnt/request_payload_bytes客户端发送请求的载荷大小srv/request_payload_bytes服务端收到请求的载荷大小clnt/response_payload_bytes客户端收到响应的载荷大小srv/response_payload_bytes服务端发送响应的载荷大小。请求/响应序列化Request/Response Serializationclnt/request_serialization_nsClientTraceAnnotationFilter客户端序列化请求的总耗时clnt/response_deserialization_nsClientTraceAnnotationFilter客户端反序列化响应的总耗时srv/request_deserialization_ns由 Scrooge 生成服务端反序列化请求的总耗时srv/response_serialization_ns由 Scrooge 生成服务端序列化响应的总耗时。重试Retry—— 由RetryFilter产生finagle.retry记录发生了一次重试。采样Sampling—— 由SamplingTracer产生zipkin.sampling_rate在 trace 根部记录采样率见上文SamplingTracer.sampleTrace中写入BinaryAnnotation(zipkin.sampling_rate, sampler.sampleRate.toDouble)的实现。超时Timeout—— 由TimeoutFilter产生finagle.timeout记录发生了一次超时。卸载Offload—— 由OffloadFilter产生clnt/OffloadFilter: Offloaded continuation from IO threads to pool with ${num} workers客户端把请求延续卸载到另一个线程池时包含目标池的 worker 数量srv/OffloadFilter: Offloaded continuation from IO threads to pool with ${size} workers服务端卸载时的同类信息。暗流量DarkTraffic—— 由DarkTrafficFilter产生clnt/dark_request标识该 Span 是暗请求dark request的二进制注解clnt/dark_request_key同时携带在明、暗两个请求中、具有相同 id 的注解用于把两个请求关联识别为一对。实战要点小结综合文档与源码使用 Finagle 分布式追踪时有几个要点值得牢记启用最简单把finagle-zipkin-scribe加入 classpathDefaultTracer会通过ServiceLoader自动发现并启用它Scribe 目标地址通过-com.twitter.finagle.zipkin.host默认localhost:1463配置多后端转发用BroadcastTracer它会过滤 null tracer 并做采样决策合并子 tracer 中任一采样则整体采样高流量务必配置采样-com.twitter.finagle.zipkin.initialSampleRate取值必须在[0.0, 1.0]显式设置后DefaultSampler将以它为最终采样率不再允许运行时覆盖避免NullTracer它不会阻止 trace 信息继续传播可能造成孤儿 Span自定义注解用TraceAPITrace.recordBinary记录无时间戳的键值信息Trace.traceLocal划分进程内局部 SpanTrace.time记录代码块耗时——三者结合可以精确剖析本地计算与分布式调用的相对关系读注解先看前缀clnt/与srv/前缀分别标识客户端与服务端视角srv/request_deadline_*系列只在相应条件下出现解读 trace 时需结合出现条件判断。通过掌握以上机制你不仅能看懂 Zipkin 中每一条 Span 和注解的来源还能按需定制自己的 tracer 与注解让分布式系统的每一次调用都有迹可循。赞分享后端RPC框架【免费下载链接】finagleA fault tolerant, protocol-agnostic RPC system项目地址https://gitcode.com/gh_mirrors/fi/finagle点击查看免费下载相关推荐Finagle OpenCensus Tracing 模块解析让 Finagle 客户端与服务端无缝接入 OpenCensus 分布式追踪Finagle OpenCensus Tracing 模块解析让 Finagle 客户端与服务端无缝接入 OpenCensus 分布式追踪 本文围绕 fina后端RPC框架Grafana Tempo 分布式追踪入门理解 Trace、Span 与 Trace ID 的核心概念Grafana Tempo 分布式追踪入门理解 Trace、Span 与 Trace ID 的核心概念 导读 本文是 Grafana Tempo 追踪Tr后端可观测性链路追踪CAI Agents SDK 内置追踪Tracing体系详解Trace、Span 与自定义导出链路CAI Agents SDK 内置追踪Tracing体系详解Trace、Span 与自定义导出链路 CAICybersecurity AI的 Agen人工智能AI Agent网络安全渗透测试工具调用AI 评测上一篇ZjDroid 动态逆向分析工具指南下一篇Zipline 项目使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
后端RPC框架【免费下载链接】finagleA fault tolerant, protocol-agnostic RPC system项目地址https://gitcode.com/gh_mirrors/fi/finagle点击查看免费下载Finagle 会为每一个 RPC 请求生成分布式追踪distributed trace数据帮助开发者理解、调试分布式系统在时间与因果上的全貌。本文以 Finagle 的 Tracing 机制为主线从 Trace/Span 的核心模型、Tracer接口与默认加载机制到TraceAPI 的自定义注解、采样Sampling、标准与二进制注解的完整清单逐层展开并结合 finagle-core 与 finagle-zipkin 系列的源码实现给出底层印证。读完本文你将能够配置并替换 Finagle 客户端/服务端的 Tracer编写自定义 Filter 向当前 Trace 写入业务注解利用局部 Span 与计时能力做进程内性能剖析并读懂每一条标准注解由哪个 Filter 在什么位置产生。分布式追踪的核心模型Trace、Span 与 TraceIdFinagle 将一次请求/响应路径上的各个片段表示为Span跨度。一条完整的Trace追踪由一系列因果相关的 Span 组成当客户端发起请求、服务端接收请求、中间经过多个跳hop时每一跳都会产生自己的 Span。关键点在于同一个 Trace 中的所有 Span 共享同一个 64 位traceId这使得 Zipkin 等追踪系统能够按 traceId 把分散在各服务的 Span 重新聚合、排序并还原为一条完整调用链同样在客户端与服务端之间Span id 也是共享的客户端产生的 Span 与服务端产生的对应 Span 通过共同的 id 关联起来。从源码看TraceId本质上是三元组的组合TraceId.scalatrace id整个请求所有 Span 共享的公共 idspan id本次请求片段单个 RPC 或进程内活动独有的 idparent id触发当前 Span 的父请求的 id。文档中的示例很好地说明了跨服务传播时的形态TRACE ID SPAN ID PARENT ID SERVICE M e4bbb7c0f6a2ff07.a5f47e9fced314a2:694eb2f05b8fd7d1 | | | ----------------- | | v v SERVICE N e4bbb7c0f6a2ff07.263ed9c65773b08:a5f47e9fced314a2Service M 调用 Service N 时两边的traceId相同e4bbb7c0f6a2ff07而 Service N 的 Span 的 parent id 恰好是 Service M 的 span ida5f47e9fced314a2由此形成父子链。对于请求中第一个 Span其 trace id、span id、parent id 三者相同如34429b04b6bbf478.34429b04b6bbf478:34429b04b6bbf478。关于 id 的更多细节SpanId是对Long的封装其字符串形式为无符号 64 位十六进制SpanId.scalaTraceId支持可选的高 64 位traceIdHigh从而兼容 128 位 trace id。在 Trace.scala 中有一个全局 flagobject traceId128Bit extends GlobalFlagBoolean. )即通过-com.twitter.finagle.tracing.traceId128Bittrue可让新的根 Span 使用 128 位 trace id默认 64 位。TraceId.serialize的线上格式为大端序spanId:8 parentId:8 traceId:8 flags:8 (traceIdHigh:8)共 32 字节64 位或 40 字节128 位。追踪数据本身以Record为单位每条Record包含traceId、事件发生时间timestamp、annotation以及可选的durationRecord.scala。这些 Record 在请求路径的每一跳被收集并发送到存储端。追踪系统的配置默认 Tracer 与 ServiceLoader 加载机制Finagle 默认使用DefaultTracerDefaultTracer.scala。它的工作方式是借助 Java 的ServiceLoader从 classpath 中所有已包含的 artifact 里加载Tracer实现并将它们统一包装在一个BroadcastTracer下object DefaultTracer extends Tracer with Proxy { private[this] val tracers LoadService[Tracer]() ... volatile var self: Tracer BroadcastTracer(tracers) ... }也就是说开箱即用只要把finagle-zipkin-scribe包加入 classpath就会自动启用一个通过 Scribe 协议向 Zipkin 发送 Span 的 tracer无需任何代码改动。这也解释了为什么官方文档把添加依赖视为最简单的启用方式。如果你希望全局安装自己的 tracer可以提供一个实现了TracerAPI 的类在 jar 的META-INF/services中按ServiceLoader规范注册该类。Tracer接口Tracer.scala只有两个必须实现的方法外加两个带默认实现的方法record(record: Record): Unit—— 记录一条追踪事件sampleTrace(traceId: TraceId): Option[Boolean]—— 决定是否采样该 traceSome(true)保留、Some(false)丢弃、None表示把决策推迟给下游服务Tracer.SomeTrue/Tracer.SomeFalse是现成的常量getSampleRate: Float—— 采样率0.0~1.0若采样由其他因素决定则返回NaNisActivelyTracing(traceId)默认实现—— 当traceId.sampled为None时返回truetracer 仍活跃但把决策留给子服务为Some(decision)时尊重该决策。此外Tracer还有一个isNull方法默认falseNullTracer会覆盖它为true——这被TraceInitializerFilter等组件用来短路空 tracer避免无谓的上下文切换。在代码中覆盖 TracerBroadcastTracer 实战示例Tracer 不仅可以在全局安装也可以在创建客户端或服务端时指定。文档给出了一个经典示例用BroadcastTracer同时把 trace 发送到 Zipkin经 Scribe和标准输出consoleimport com.twitter.finagle.Http import com.twitter.finagle.tracing.{BroadcastTracer, Record, TraceId, Tracer} import com.twitter.finagle.zipkin.thrift.ZipkinTracer object SystemOutTracer extends Tracer { def record(record: Record): Unit println(record) def sampleTrace(traceId: TraceId): Option[Boolean] Some(false) } val client Http.client .withTracer(BroadcastTracer(Seq( ZipkinTracer.mk(), SystemOutTracer )))注意示例中SystemOutTracer.sampleTrace返回Some(false)表示它自己不做采样决策、仅原样转发记录——采样与否由BroadcastTracer内部的合并逻辑决定。从 BroadcastTracer.scala 的源码可以看到其采样合并规则任何一个子 tracer 返回Some(true)则整体采样所有子 tracer 都返回Some(false)才整体不采样否则返回None把决策留给下游。BroadcastTracer.apply还有优化若过滤掉 null tracer 后只剩 0/1/2/3 个 tracer会分别退化为NullTracer、原 tracer 或专门的Two/Three内部类减少分发开销。关于 NullTracer 的重要警告Finagle 还提供NullTracerNullTracer.scala它丢弃所有 trace 消息。但即使把NullTracer传给withTracerFinagle 客户端仍然会继续向对端传播 trace 信息。这可能导致一个令人惊讶的副作用如果 trace 正在被 Zipkin 之类的分布式追踪服务聚合下游 Span 会因为缺少本端记录而变成孤儿 span。因此官方明确不建议在生产环境使用NullTracer。这从NullTracer的注释也能印证它不会阻止 trace 信息传播到下一跳只会让本主机不记录任何信息。可用 Tracer 一览Finagle 及其生态提供了多种现成的 Tracer 实现按职责分工Tracer说明NullTracer丢弃所有 trace。未配置任何 tracer 时的默认行为BroadcastTracer在过滤后为空时也会退化为它BroadcastTracer把同一条 trace 转发给任意数量的子 tracer适合同时发往多个后端系统。默认情况下所有通过 ServiceLoader 加载的 tracer 都被打包在同一个BroadcastTracer下SamplingTracer只把一部分 trace 转发给底层存储适合请求量高、不想压垮追踪系统的场景。采样决策在新 trace 创建时确定一旦 trace 通过采样该决策会被记录并随 trace 一起传播保证沿途所有 Span 一致通过采样RawZipkinTracer抽象的SamplingTracer负责把 trace 格式化为 Zipkin 可消费的形态但传输层开放给子类实现ScribeZipkinTracer一种RawZipkinTracer用 Scribe 协议把 Span 发送给 Zipkin。随finagle-zipkin-scribeartifact 提供暴露以下配置 flagSamplingTracer的源码SamplingTracer.scala展示了它的双通道过滤record时先经sampler.sampleRecord(record)判断该 record 是否属于被采样 trace只有通过才转交底层 tracersampleTrace时调用sampler.sampleTrace做出决策若 trace 首次被采样还会写入zipkin.sampling_rate二进制注解把采样率固化在 trace 根部这正是文档中Sampling一节所列注解的来源。而ScribeZipkinTracerScribeZipkinTracer.scala的无参构造供 ServiceLoader 使用从全局 flaghost读取 Scribe 地址并配合core.DefaultSampler工作。ScribeZipkinTracer 的配置 flagScribeZipkinTracer暴露两个命令行 flag-com.twitter.finagle.zipkin.hostScribe 服务器地址。定义在 finagle-zipkin-scribe 的 Flags.scala默认值为new InetSocketAddress(localhost, 1463)即本地 1463 端口-com.twitter.finagle.zipkin.initialSampleRate初始采样率。定义在 finagle-zipkin-core 的 Flags.scala类型为Float其Flaggable会校验取值必须在[0.0, 1.0]区间越界会抛出IllegalArgumentException。DefaultSamplerDefaultSampler.scala的逻辑是若用户显式设置了initialSampleRateflag则始终以它为准、不允许代码运行时覆盖否则采用默认采样率并允许运行时通过SamplingTracer.setSampleRate调整。使用 Trace API 添加自定义注解当前活跃 trace 的信息存放在 Finagle 的Context中详见 Contexts.rst而TraceAPITrace.scala是访问与操作当前 trace 的便捷门面它内部通过Contexts.local持有当前Seq[Tracer]通过Contexts.broadcast持有TraceId并支持letId、letTracer、letClear等上下文切换方法。由于每次操作都要做Contexts查找源码注释建议在频繁使用时先通过Trace()捕获一个Tracing实例以批量复用查找结果。最常见的需求是在请求处理过程中记录自定义信息。文档给出了一个在SimpleFilter里记录请求头值的例子import com.twitter.finagle.http.{Request, Response} import com.twitter.finagle.tracing.Trace import com.twitter.finagle.{Service, SimpleFilter} import com.twitter.util.Future class MyFilter extends SimpleFilter[Request, Response] { def apply(request: Request, service: Service[Request, Response]): Future[Response] { val header request.headerMap(Special-Header) Trace.recordBinary(special-header, header) service(request) } }Trace.recordBinary(key, value)写入的是二进制注解binary annotation一个从字符串 key 到二进制 value 的简单映射不携带时间戳。与之相对的是普通注解annotation它描述某个时间点发生的事件并携带时间戳。两类注解的差异决定了它们的用途例如 Client Send 事件发生在某一具体时刻、带时间戳因此可以和 Wire Send 事件做先后排序与耗时对比用于分析请求从客户端代码交到网卡、再到远端服务器的耗时而二进制注解更适合记录请求发生时的系统局部状态例如 GC 当时在做什么。Annotation是密封 ADTAnnotation.scala包含WireSend、ClientSend、ServerRecv、Message、ServiceName、Rpc、ClientAddr、ServerAddr、LocalAddr、BinaryAnnotation(key, value)等变体——上述标准注解表格中的所有条目都能在这个 ADT 中找到对应。另外Trace.scala 还提供了两个进程级全局 flag-com.twitter.finagle.tracing.enabled默认true设为false时关闭本进程所有追踪记录但官方注释明确警告生产环境不建议禁用追踪代码层面也有Trace.enable()/Trace.disable()/Trace.enabled对应的开关。追踪系统的初始化TraceInitializationFilter追踪系统由TraceInitializationFilterTraceInitializationFilter.scala初始化。它存在于 Finagle 默认栈default stack的客户端与服务端两侧且总是位于 Filter 链的最前端即Stack的最里层这样带有 trace 支持的协议可以覆盖 Span 重置逻辑同时仍能在此处被正确上报。该 Filter 的职责是为每个请求建立正确的追踪上下文——要么复用传入的 trace id要么生成一个新的——并在进入服务前把 tracer 压入当前上下文。其apply逻辑结合newId参数区分客户端/服务端为tracer 为 null 时客户端会Trace.letId(Trace.nextId)生成新 id服务端则直接放行非 null 时客户端调用Trace.letTracerAndNextId(tracer)推入 tracer 并生成下一个 TraceId服务端调用Trace.letTracer(tracer)只推入 tracer沿用传入 id若启用了 partitioningfanout true则会用FanoutTracer包裹以便把记录延迟到拿到 peer trace id 后再冲刷保证多分区场景下 trace 不被拆散。客户端与服务端在栈中的装配分别通过TraceInitializerFilter.clientModule与serverModule完成。除此之外AnnotatingTracingFilter是标准注解的通用载体它根据构造参数在服务调用前/后无论成败记录注解并在失败时通过afterFailure回调生成错误注解出于保证注解顺序的目的它用transform而非respond来强制排序否则可能出现 Client Receive 先于 Client Wire Receive 的乱序。围绕它派生了三个标准 FilterServerTracingFilter记录ServerRecv/ServerSend/ServerSendError前缀srvClientTracingFilter记录ClientSend/ClientRecv/ClientRecvError前缀clnt并额外记录finagle.version、finagle.label以及非空的dtab.local/dtab.limited等元数据WireTracingFilter记录传输层事件WireSend/WireRecv/WireRecvError客户端前缀clnt、服务端前缀srv。此外还有ResourceTracingFilter服务端记录srv/finagle_cputime_ns与srv/finagle_continuations_executed资源消耗和TracelessFilter用Trace.letClear清除追踪信息两个辅助组件。局部 Span 与计时剖析进程内行为每个请求都运行在一个 Span 的作用域内该 Span 在请求被接收或初始请求发出时创建。但有时需要把请求处理中的某些阶段拆分成独立事件来分析——这就要用到局部 Spanlocal span它完全存在于单个进程内部适合观察本地计算与外部请求之间的因果关系以及它们彼此的相对时序与耗时。局部 Span 通过Trace#traceLocal创建import com.twitter.finagle.tracing.Trace def chainOfEvents(): Int ??? Trace.traceLocal(important_work) { // perform within the context of a new SpanId chainOfEvents() }代码块会在一个新的 SpanId上下文中执行从而把这段工作从当前 Span 中切分出来。更进一步可以对操作计时并把结果记录进 trace 上下文import com.twitter.finagle.tracing.Trace def complexComputation(): Int ??? val result Trace.time(complexComputation_ns) { // record how long the computation took complexComputation() }Trace.time返回块内计算的结果同时把耗时写入注解。局部 Span 计时的组合使得本地一段计算的性能可以直接与其它分布式计算做横向对比——这正是文档强调的用法理解本地计算与外部请求的相对耗时关系。标准注解Standard Annotations全表Finagle 在请求路径的关键位置自动记录以下标准注解每一类都由对应 Filter 产生Annotation描述产生位置Wire Send消息被交给传输层的时间WireTracingFilterWire Receive传输层收到消息的时间WireTracingFilterWire Receive Error传输层产生的任意错误消息WireTracingFilterClient Send客户端发出请求的时间ClientTracingFilterClient Receive客户端收到响应的时间ClientTracingFilterClient Receive Error客户端栈产生的任意错误ClientTracingFilterServer Send服务端收到请求的时间ServerTracingFilterServer Receive服务端发出响应的时间ServerTracingFilterServer Send Error服务端栈产生的任意错误ServerTracingFilterService Name该 Span 起源处的服务名TraceInitializationFilterRPCRPC 名称与方法由 service/client 自行记录Message信息性消息RetryFilter、TimeoutFilterClient Address请求的来源地址ClientDispatcherServer Address请求的终端地址DestinationTracingLocal AddressSpan 生成处的本地地址DestinationTracing从 TraceInitializerFilter.scala 的源码可以看到这些注解在栈中的真实装配方式ServerTracingFilter/ClientTracingFilter在 tracer 非空时把TracingFilter接入栈WireTracingFilter的客户端模块记录WireSend→WireRecv、服务端模块记录WireRecv→WireSend共同构成客户端 send/receive → 线上 send/receive → 服务端 recv/send的完整时序链。附加二进制注解Additional Binary Annotations详解除标准注解外Finagle 各模块还会写入一批语义明确的二进制注解文档按功能域逐一列出备份请求Backup Requests—— 由BackupRequestFilter产生srv/backup_request_processing服务端处理备份请求时生成clnt/backup_request_threshold_ms配置的备份请求触发阈值毫秒clnt/backup_request_span_id备份请求的 span id用于区分哪些 Span 属于主请求、哪些属于备份请求Client Backup Request IssuedMessage 注解客户端发出备份请求时生成Client Backup Request WonMessage 注解备份请求先于主请求完成时生成Client Backup Request LostMessage 注解备份请求晚于主请求完成时生成。截止时间DeadlinesFinagle 默认只在服务端处理 deadline因此文档只列出srv/前缀注解客户端同样可追踪但默认不产生srv/request_deadlinedeadline 到达的时刻srv/request_deadline_remaining_msdeadline 前剩余毫秒数仅当 deadline 尚未到达时出现srv/request_deadline_exceeded_ms超出 deadline 的毫秒数仅当 deadline 已被超出时出现srv/request_deadline_rejected请求是否因超时被拒绝的布尔值仅当请求被拒绝时出现。垃圾回收Garbage Collection—— 由MkJvmFilter产生GC StartMessage 注解请求前最近一分钟内所有 GC 事件的起始时间戳GC EndMessage 注解请求前最近一分钟内所有 GC 事件的结束时间戳jvm/gc_count请求前最近一分钟内的 GC 次数jvm/gc_ms请求前最近一分钟内花在 GC 上的总时长。载荷大小Payload Size—— 由PayloadSizeFilter产生clnt/request_payload_bytes客户端发送请求的载荷大小srv/request_payload_bytes服务端收到请求的载荷大小clnt/response_payload_bytes客户端收到响应的载荷大小srv/response_payload_bytes服务端发送响应的载荷大小。请求/响应序列化Request/Response Serializationclnt/request_serialization_nsClientTraceAnnotationFilter客户端序列化请求的总耗时clnt/response_deserialization_nsClientTraceAnnotationFilter客户端反序列化响应的总耗时srv/request_deserialization_ns由 Scrooge 生成服务端反序列化请求的总耗时srv/response_serialization_ns由 Scrooge 生成服务端序列化响应的总耗时。重试Retry—— 由RetryFilter产生finagle.retry记录发生了一次重试。采样Sampling—— 由SamplingTracer产生zipkin.sampling_rate在 trace 根部记录采样率见上文SamplingTracer.sampleTrace中写入BinaryAnnotation(zipkin.sampling_rate, sampler.sampleRate.toDouble)的实现。超时Timeout—— 由TimeoutFilter产生finagle.timeout记录发生了一次超时。卸载Offload—— 由OffloadFilter产生clnt/OffloadFilter: Offloaded continuation from IO threads to pool with ${num} workers客户端把请求延续卸载到另一个线程池时包含目标池的 worker 数量srv/OffloadFilter: Offloaded continuation from IO threads to pool with ${size} workers服务端卸载时的同类信息。暗流量DarkTraffic—— 由DarkTrafficFilter产生clnt/dark_request标识该 Span 是暗请求dark request的二进制注解clnt/dark_request_key同时携带在明、暗两个请求中、具有相同 id 的注解用于把两个请求关联识别为一对。实战要点小结综合文档与源码使用 Finagle 分布式追踪时有几个要点值得牢记启用最简单把finagle-zipkin-scribe加入 classpathDefaultTracer会通过ServiceLoader自动发现并启用它Scribe 目标地址通过-com.twitter.finagle.zipkin.host默认localhost:1463配置多后端转发用BroadcastTracer它会过滤 null tracer 并做采样决策合并子 tracer 中任一采样则整体采样高流量务必配置采样-com.twitter.finagle.zipkin.initialSampleRate取值必须在[0.0, 1.0]显式设置后DefaultSampler将以它为最终采样率不再允许运行时覆盖避免NullTracer它不会阻止 trace 信息继续传播可能造成孤儿 Span自定义注解用TraceAPITrace.recordBinary记录无时间戳的键值信息Trace.traceLocal划分进程内局部 SpanTrace.time记录代码块耗时——三者结合可以精确剖析本地计算与分布式调用的相对关系读注解先看前缀clnt/与srv/前缀分别标识客户端与服务端视角srv/request_deadline_*系列只在相应条件下出现解读 trace 时需结合出现条件判断。通过掌握以上机制你不仅能看懂 Zipkin 中每一条 Span 和注解的来源还能按需定制自己的 tracer 与注解让分布式系统的每一次调用都有迹可循。赞分享后端RPC框架【免费下载链接】finagleA fault tolerant, protocol-agnostic RPC system项目地址https://gitcode.com/gh_mirrors/fi/finagle点击查看免费下载相关推荐Finagle OpenCensus Tracing 模块解析让 Finagle 客户端与服务端无缝接入 OpenCensus 分布式追踪Finagle OpenCensus Tracing 模块解析让 Finagle 客户端与服务端无缝接入 OpenCensus 分布式追踪 本文围绕 fina后端RPC框架Grafana Tempo 分布式追踪入门理解 Trace、Span 与 Trace ID 的核心概念Grafana Tempo 分布式追踪入门理解 Trace、Span 与 Trace ID 的核心概念 导读 本文是 Grafana Tempo 追踪Tr后端可观测性链路追踪CAI Agents SDK 内置追踪Tracing体系详解Trace、Span 与自定义导出链路CAI Agents SDK 内置追踪Tracing体系详解Trace、Span 与自定义导出链路 CAICybersecurity AI的 Agen人工智能AI Agent网络安全渗透测试工具调用AI 评测上一篇ZjDroid 动态逆向分析工具指南下一篇Zipline 项目使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
