OpenTelemetry 分布式链路追踪 (vertx-opentelemetry)

该组件提供了 Vert.x 与现代云原生可观测性行业标准 OpenTelemetry 的深度集成。

Vertx vertx = Vertx.vertx(new VertxOptions()
  .setTracingOptions(
    new OpenTelemetryOptions()
  )
);

你也可以显式传入自定义配置的 OpenTelemetry 实例以获得更强大的精细化控制权：

Vertx vertx = Vertx
  .builder()
  .withTracer(new OpenTelemetryTracingFactory(openTelemetry))
  .build();

若仅引入本依赖库，Vert.x 将默认使用 noop 空实现 Tracer（生成的 Trace ID 与 Span ID 均为全零虚拟值）。要采集真实的链路追踪数据，必须引入并初始化 OpenTelemetry SDK：

SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
  .setTracerProvider(sdkTracerProvider)
  .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
  .buildAndRegisterGlobal();

Vertx vertx = Vertx
  .builder()
  .withTracer(new OpenTelemetryTracingFactory(openTelemetry))
  .build();

本项目专门实现并注册了 OpenTelemetry 的 ContextStorageProvider SPI。当在 Vert.x 事件循环线程上调用时，底层链路上下文将自动存储在 Vert.x 的 Context 中；在非 Vert.x 线程上则自动平滑降级至默认存储。

若类路径中存在多个 ContextStorageProvider 实现，可以通过 JVM 系统属性强制 OpenTelemetry 优先选择 Vert.x 实现：

-Dio.opentelemetry.context.contextStorageProvider=io.vertx.tracing.opentelemetry.VertxContextStorageProvider

链路追踪策略 (Tracing Policy)

追踪策略定义了在开启 Tracing 时特定组件的具体行为模式：

PROPAGATE：若当前存在活跃 Trace 则在其下上报 Span，若不存在则不主动创建新 Trace。
ALWAYS：在活跃 Trace 下上报 Span；若不存在活跃 Trace 则强制创建新的活跃 Trace 根节点。
IGNORE：该组件完全不参与任何链路追踪。

追踪策略通常在各组件的 Options 配置项中进行声明。

HTTP 服务端与客户端链路追踪

Vert.x HTTP 服务端与客户端会在处理 HTTP 请求前后自动上报 Span：

name：HTTP 请求方法（如 GET, POST）
Tags 标签集：
- http.method：HTTP 请求方法
- http.url：完整的请求 URL
- http.status_code：HTTP 状态码字符串

HTTP 服务端默认的追踪策略为 ALWAYS，可以通过 setTracingPolicy 自由覆盖：

HttpServer server = vertx.createHttpServer(new HttpServerOptions()
  .setTracingPolicy(TracingPolicy.IGNORE)
);

HTTP 客户端默认的追踪策略为 PROPAGATE，同样可通过 setTracingPolicy 进行调整：

HttpClient client = vertx.createHttpClient(new HttpClientOptions()
  .setTracingPolicy(TracingPolicy.IGNORE)
);

EventBus 事件总线链路追踪

Vert.x EventBus 在进行组件间消息流转时会自动围绕消息交互上报 Span。

发送消息的默认策略为 PROPAGATE，你可以通过 setTracingPolicy 显式指定：

DeliveryOptions options = new DeliveryOptions().setTracingPolicy(TracingPolicy.ALWAYS);
vertx.eventBus().send("the-address", "foo", options);

Zipkin

OpenTracing