Monitoring
API docs

Vertx Zipkin Tracing

Vert.x integrates with Zipkin thanks to the Zipkin Brave client.

Vert.x uses the ZipKin HTTP sender based using a Vert.x HTTP Client reporting spans to http://localhost:9411/api/v2/spans in JSON format.

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

The service name is the mandatory Zipkin service name. If you don’t set it, then a-service will be used instead.

You can configure the sender to use a specific URL

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

The default sender uses a single HTTP connection in plain text with compressed bodies.

You can override the configuration of the HTTP sender with custom HttpClientOptions.

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

Finally, you can set a custom ZipKin Tracing allowing for greater control over the configuration.

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

Tracing policy

The tracing policy defines the behavior of a component when tracing is enabled:

  • PROPAGATE: the component reports a span in the active trace

  • ALWAYS: the component reports a span in the active trace or creates a new active trace

  • IGNORE: the component will not be involved in any trace.

The tracing policy is usually configured in the component options.

HTTP tracing

The Vert.x HTTP server and client reports span around HTTP requests:

  • operationName: the HTTP method

  • tags

  • http.method: the HTTP method

  • http.url: the request URL

  • http.status_code: the HTTP status code

The default HTTP server tracing policy is ALWAYS, you can configure the policy with setTracingPolicy

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

The default HTTP client tracing policy is PROPAGATE, you can configure the policy with setTracingPolicy

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

EventBus tracing

The Vert.x EventBus reports spans around message exchanges.

The default sending policy is PROPAGATE, you can configure the policy with setTracingPolicy.

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