系统监控 (Monitoring)

Zipkin 分布式链路追踪 (vertx-zipkin)

Vert.x 依托 Zipkin Brave 客户端提供了对 Zipkin 分布式追踪系统的集成。

模块内部基于高性能的 Vert.x HTTP Client 实现 Zipkin HTTP 发送器，默认以 JSON 格式向 http://localhost:9411/api/v2/spans 端点上报链路 Span：

Vertx vertx = Vertx.vertx(new VertxOptions()
  .setTracingOptions(
    new ZipkinTracingOptions().setServiceName("A cute service")
  )
);

服务名称（Service Name）是 Zipkin 的必填标识；若未显式指定，默认采用 a-service。

你可以通过配置项指定自定义的上报端点 URL：

Vertx vertx = Vertx.vertx(new VertxOptions()
  .setTracingOptions(
    new ZipkinTracingOptions()
      .setSenderOptions(new HttpSenderOptions().setSenderEndpoint(senderEndpoint))
  )
);

默认的发送器采用单一明文 HTTP 连接，并对上报数据体执行流式压缩。

你可以利用自定义的 HttpClientOptions 全面覆盖发送器的网络配置（例如开启 SSL/TLS 安全通道）：

Vertx vertx = Vertx.vertx(new VertxOptions()
  .setTracingOptions(
    new ZipkinTracingOptions()
      .setSenderOptions(new HttpSenderOptions()
        .setSenderEndpoint(senderEndpoint)
        .setSsl(true)
        .setKeyCertOptions(sslOptions))
  )
);

你也可以传入自定义构造的 Zipkin Tracing 实例以获得更深度的配置自由度：

Vertx vertx = Vertx
  .builder()
  .withTracer(new ZipkinTracerFactory(tracing))
  .build();

链路追踪策略 (Tracing Policy)

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

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

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

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

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

operationName：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);

gRPC Eventbus Bridge

OpenTelemetry