= Vertx OpenTracing

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

You can configure Vert.x to use the Jaeger client configured via
https://github.com/jaegertracing/jaeger-client-java/blob/master/jaeger-core/README.md#configuration-via-environment[Environment]

[source,$lang]
----
{@link examples.OpenTracingExamples#ex1}
----

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

[source,$lang]
----
{@link examples.OpenTracingExamples#ex2}
----

== Tracing policy

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

- {@link io.vertx.core.tracing.TracingPolicy#PROPAGATE}: the component reports a span in the active trace
- {@link io.vertx.core.tracing.TracingPolicy#ALWAYS}: the component reports a span in the active trace or creates a new active trace
- {@link io.vertx.core.tracing.TracingPolicy#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 {@link io.vertx.core.http.HttpServerOptions#setTracingPolicy}

[source,$lang]
----
{@link examples.OpenTracingExamples#ex3}
----

The default HTTP client tracing policy is `PROPAGATE`, you can configure the policy with {@link io.vertx.core.http.HttpClientOptions#setTracingPolicy}

[source,$lang]
----
{@link examples.OpenTracingExamples#ex4}
----

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

[source,$lang]
----
{@link examples.OpenTracingExamples#ex5}
----

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 {@link io.vertx.core.eventbus.DeliveryOptions#setTracingPolicy}.

[source,$lang]
----
{@link examples.OpenTracingExamples#ex6}
----
