# Vertx OpenTracing

Vert.x integrates with OpenTracing thanks to the Jaeger client.

You can configure Vert.x to use the Jaeger client configured via Environment

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

You can also pass a custom `Tracer` allowing for greater control over the configuration.

    Vertx vertx = Vertx.vertx(new VertxOptions()
      .setTracingOptions(
        new OpenTracingOptions(tracer)
      )
    );

## 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)
    );

To initiate a trace for a client call, you need to create it first and make Vert.x aware of it by using `OpenTracingUtil.setSpan`:

    Span span = tracer.buildSpan("my-operation")
      .withTag("some-key", "some-value")
      .start();
    OpenTracingUtil.setSpan(span);
    // Do something, e.g. client request
    span.finish();

In an HTTP scenario between two Vert.x services, a span will be created client-side, then the trace context will be propagated server-side and another span will be added to the trace.

## 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);