= Vertx OpenTelemetry

Vert.x integration with OpenTelemetry.

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions()
  .setTracingOptions(
    new OpenTelemetryOptions()
  )
);
----

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

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions()
  .setTracingOptions(
    new OpenTelemetryOptions(openTelemetry)
  )
);
----

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.

[source,java]
----
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
  .setTracerProvider(sdkTracerProvider)
  .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
  .buildAndRegisterGlobal();

vertxOptions.setTracingOptions(new OpenTelemetryOptions(openTelemetry));
----

[NOTE]
====
This project provides an OpenTelemetry `ContextStorageProvider` that uses the Vert.x `link:../../apidocs/io/vertx/core/Context.html[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:

[source]
----
-Dio.opentelemetry.context.contextStorageProvider=io.vertx.tracing.opentelemetry.VertxContextStorageProvider
----
====

== Tracing policy

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

- `link:../../apidocs/io/vertx/core/tracing/TracingPolicy.html#PROPAGATE[PROPAGATE]`: the component reports a span in the active trace
- `link:../../apidocs/io/vertx/core/tracing/TracingPolicy.html#ALWAYS[ALWAYS]`: the component reports a span in the active trace or creates a new active trace
- `link:../../apidocs/io/vertx/core/tracing/TracingPolicy.html#IGNORE[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 `link:../../apidocs/io/vertx/core/http/HttpServerOptions.html#setTracingPolicy-io.vertx.core.tracing.TracingPolicy-[setTracingPolicy]`

[source,java]
----
HttpServer server = vertx.createHttpServer(new HttpServerOptions()
  .setTracingPolicy(TracingPolicy.IGNORE)
);
----

The default HTTP client tracing policy is `PROPAGATE`, you can configure the policy with `link:../../apidocs/io/vertx/core/http/HttpClientOptions.html#setTracingPolicy-io.vertx.core.tracing.TracingPolicy-[setTracingPolicy]`

[source,java]
----
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 `link:../../apidocs/io/vertx/core/eventbus/DeliveryOptions.html#setTracingPolicy-io.vertx.core.tracing.TracingPolicy-[setTracingPolicy]`.

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