# Vertx OpenTelemetry

Vert.x integration with OpenTelemetry.

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

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

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

If you only add this library, it will give you access to OpenTelemetry API with a default `noop` Tracer, which gives dummy values (all zeroes) for trace and span ids. The OpenTelemetry SDK is needed to get proper values.

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

Note | This project provides an OpenTelemetry `ContextStorageProvider` that uses the Vert.x `Context` when invoked on a Vert.x thread. Otherwise, it fallbacks to the default storage. If several `ContextStorageProvider` implementations are present on the classpath, you can force OpenTelemetry to select the Vert.x one:
    -Dio.opentelemetry.context.contextStorageProvider=io.vertx.tracing.opentelemetry.VertxContextStorageProvider

## 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:

- `name`: the HTTP method

- tags

- `http.method`: the HTTP method

- `http.url`: the request URL

- `http.status_code`: the HTTP status code (as `String`)

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