文章目录1. Tracer 接口1.1 核心定义1.2 方法定义1.2.1 创建 Span1.2.2 作用域管理1.2.3 上下文获取1.2.4 Baggage 行李透传1.3 内部类 / 内部接口1.3.1 NOOP1.3.2 SpanInScope2. OtelTracer2.1 核心定义2.2 方法定义2.2.1 构造方法2.2.2 方法实现2.3 内部类 / 内部接口2.3.1 EventPublisher 内部接口2.3.2 WrappedSpanInScope1. Tracer 接口1.1 核心定义Tracer是分布式追踪顶层入口API大量借鉴OpenZipkin Brave设计。作用创建Span、管理链路上下文、控制Span作用域、提供Baggage透传能力继承BaggageManager行李数据管理接口。相关核心概念Trace一次完整分布式请求链路Span链路内一段独立操作单元Scope作用域将Span绑定在线程上下文让下游代码日志、拦截器获取链路信息TraceContext存储traceId/spanId/parentSpanId等链路标识NOOP无操作空实现关闭追踪时使用避免大量if追踪开关判断。1.2 方法定义1.2.1 创建 SpanSpan nextSpan()根据当前作用域Span生成子Span无上下文时新建一条Trace根Span。Nullable Span nextSpan(Nullable Span parent)指定父Span创建子Spanparent为null时等价于无参nextSpan()。Span.Builder spanBuilder()获取Span构建器。需要在Span启动前批量配置属性启动后无法修改部分字段常用于Propagator提取上下文后构造Span。ScopedSpan startScopedSpan(String name)简易API。创建Span并自动绑定至当前线程作用域返回ScopedSpan调用end()同时关闭作用域。适合单线程同步业务代码。1.2.2 作用域管理SpanInScope withSpan(Nullable Span span)手动将Span置入线程作用域返回SpanInScope⚠️重要区分close()只会退出作用域不会结束Span生命周期Span必须手动调用end()。推荐搭配try-with-resources使用。传参null可以清空当前作用域。1.2.3 上下文获取CurrentTraceContext currentTraceContext()获取全局链路上下文管理器负责在线程内读写TraceContext。Nullable Span currentSpan()获取当前线程作用域内生效的Span无则返回null。Nullable SpanCustomizer currentSpanCustomizer()获取当前Span定制器无需持有Span对象即可添加Tag、事件。TraceContext.Builder traceContextBuilder()构造TraceContext构建器手动组装链路ID上下文。1.2.4 Baggage 行李透传继承自BaggageManager提供跨线程/跨服务透传自定义业务字段能力getAllBaggage()getBaggage()createBaggage()1.3 内部类 / 内部接口1.3.1 NOOP追踪关闭时使用的空实现实例所有方法调用均不产生真实埋点。TracerNOOPnewTracer(){...};1.3.2 SpanInScopeSpan作用域资源对象。职责绑定/解绑线程上下文必须执行close清理MDC、释放上下文资源防止上下文泄漏close不终止Span仅脱离作用域。interfaceSpanInScopeextendsCloseable{Overridevoidclose();}2. OtelTracer来自micrometer-tracing-bridge-otel模块2.1 核心定义OtelTracer是Tracer接口基于OpenTelemetry的桥接实现bridge。上层业务面向micrometer-tracing统一API编程底层委托OpenTelemetry SDK完成链路创建、上下文管理、Baggage透传实现可观测层框架与OTel SDK解耦切换。成员变量io.opentelemetry.api.trace.Tracer tracer原生OpenTelemetry追踪器实例底层真正创建OTelSpanBaggageManager otelBaggageManagerBaggage行李数据管理器负责跨上下文业务字段透传OtelCurrentTraceContext otelCurrentTraceContext链路上下文管理器维护线程内TraceContextEventPublisher publisher事件发布器用于上下文关闭时推送事件核心映射关系Micrometer Tracing 抽象底层 OpenTelemetry 实体SpanOtelSpan包装io.opentelemetry.api.trace.SpanTraceContextOtelTraceContext包装 OTelContextScopedSpanOtelScopedSpanSpan.BuilderOtelSpanBuilderTracer.SpanInScopeWrappedSpanInScope包装CurrentTraceContext.Scope上层面向抽象底层切换Otel实现业务代码只依赖io.micrometer.tracing.Tracer不直接依赖OTel原生API底层通过OtelTracer桥接OpenTelemetry如果需要可替换为Brave实现业务无需改动。补充关键注意点OtelTracer属于适配桥接层业务禁止直接new构造由micrometer-tracing自动装配nextSpan(parent)内部存在临时Scope切换逻辑用来兼容父上下文不在当前线程的场景Baggage能力全部委派如需开启跨服务透传需要正确配置otelBaggageManagerOTel无效SpanSpan.getInvalid()统一对外返回null对齐micrometer-tracing语义。2.2 方法定义2.2.1 构造方法OtelTracer(io.opentelemetry.api.trace.Tracer, OtelCurrentTraceContext, EventPublisher, BaggageManager)完整构造器可自定义BaggageManager支持行李透传功能。OtelTracer(io.opentelemetry.api.trace.Tracer, OtelCurrentTraceContext, EventPublisher)简化构造器内部使用NOOP空实现BaggageManager关闭行李透传。2.2.2 方法实现实现了Micrometer Tracer接口定义的所有方法Span nextSpan()Span nextSpan(Nullable Span parent)ScopedSpan startScopedSpan(String name)Span.Builder spanBuilder()TraceContext.Builder traceContextBuilder()Tracer.SpanInScope withSpan(Nullable Span span)Nullable Span currentSpan()SpanCustomizer currentSpanCustomizer()CurrentTraceContext currentTraceContext()Baggage行李透传实现BaggageManager全部方法直接委派otelBaggageManagergetAllBaggage()/getAllBaggage(TraceContext)getBaggage(String name)/getBaggage(TraceContext, String name)createBaggage(...)标记Deprecated推荐使用createBaggageInScopecreateBaggageInScope(...)创建绑定作用域的行李数据getBaggageFields()获取允许透传的行李字段列表2.3 内部类 / 内部接口2.3.1 EventPublisher 内部接口事件发布接口链路上下文关闭时推送事件。publicinterfaceEventPublisher{voidpublishEvent(Objectevent);}2.3.2 WrappedSpanInScopeSpanInScope实现类包装CurrentTraceContext.Scope。调用close()时委托释放上下文作用域。staticclassWrappedSpanInScopeimplementsSpanInScope{finalCurrentTraceContext.Scopescope;Overridepublicvoidclose(){this.scope.close();}}