io.opentracing

Interface Tracer

All Superinterfaces:

ActiveSpanSource

public interface Tracer
extends ActiveSpanSource

Tracer is a simple, thin interface for Span creation and propagation across arbitrary transports.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Tracer.SpanBuilder

Method Summary

Modifier and Type	Method and Description
Tracer.SpanBuilder	buildSpan(String operationName) Return a new SpanBuilder for a Span with the given `operationName`.
<C> SpanContext	extract(Format<C> format, C carrier) Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary.
<C> void	inject(SpanContext spanContext, Format<C> format, C carrier) Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries.

Methods inherited from interface io.opentracing.ActiveSpanSource

activeSpan, makeActive

Method Detail

buildSpan

Tracer.SpanBuilder buildSpan(String operationName)

Return a new SpanBuilder for a Span with the given `operationName`.

You can override the operationName later via BaseSpan.setOperationName(String).

A contrived example:

   Tracer tracer = ...

   // Note: if there is a `tracer.activeSpan()`, it will be used as the target of an implicit CHILD_OF
   // Reference for "workSpan" when `startActive()` is invoked.
   try (ActiveSpan workSpan = tracer.buildSpan("DoWork").startActive()) {
       workSpan.setTag("...", "...");
       // etc, etc
   }

   // It's also possible to create Spans manually, bypassing the ActiveSpanSource activation.
   Span http = tracer.buildSpan("HandleHTTPRequest")
                     .asChildOf(rpcSpanContext)  // an explicit parent
                     .withTag("user_agent", req.UserAgent)
                     .withTag("lucky_number", 42)
                     .startManual();
 

inject

<C> void inject(SpanContext spanContext,
                Format<C> format,
                C carrier)

Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries.

Example:

 Tracer tracer = ...
 Span clientSpan = ...
 TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
 tracer.inject(span.context(), Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
 

Type Parameters:

C - the carrier type, which also parametrizes the Format.

Parameters:

spanContext - the SpanContext instance to inject into the carrier

format - the Format of the carrier

carrier - the carrier for the SpanContext state. All Tracer.inject() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer.

See Also:

Format, Format.Builtin

extract

<C> SpanContext extract(Format<C> format,
                        C carrier)

Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary.

Example:

 Tracer tracer = ...
 TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
 SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
 ... = tracer.buildSpan('...').asChildOf(spanCtx).startActive();
 

If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an IllegalArgumentException.

Type Parameters:

C - the carrier type, which also parametrizes the Format.

Parameters:

format - the Format of the carrier

carrier - the carrier for the SpanContext state. All Tracer.extract() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer.

Returns:

the SpanContext instance holding context to create a Span.

See Also:

Format, Format.Builtin