io.opentracing

Interface Tracer

All Superinterfaces:

AutoCloseable, Closeable

public interface Tracer
extends Closeable

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
Scope	activateSpan(Span span) Make a Span instance active for the current context (usually a thread).
Span	activeSpan()
Tracer.SpanBuilder	buildSpan(String operationName) Return a new SpanBuilder for a Span with the given `operationName`.
void	close() Closes the Tracer, and tries to flush the in-memory collection to the configured persistance store.
<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.
ScopeManager	scopeManager()

Method Detail

scopeManager

ScopeManager scopeManager()

Returns:

the current ScopeManager, which may be a noop but may not be null.

activeSpan

Span activeSpan()

Returns:

the active Span. This is a shorthand for Tracer.scopeManager().activeSpan().

activateSpan

Scope activateSpan(Span span)

Make a Span instance active for the current context (usually a thread). This is a shorthand for Tracer.scopeManager().activate(span).

Returns:

a Scope instance to control the end of the active period for the Span. It is a programming error to neglect to call Scope.close() on the returned instance, and it may lead to memory leaks as the Scope may remain in the thread-local stack.

buildSpan

Tracer.SpanBuilder buildSpan(String operationName)

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

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

A contrived example:

   Tracer tracer = ...

   // Note: if there is a `tracer.activeSpan()` instance, it will be used as the target
   // of an implicit CHILD_OF Reference when `start()` is invoked,
   // unless another Span reference is explicitly provided to the builder.
   Span span = tracer.buildSpan("HandleHTTPRequest")
                     .asChildOf(rpcSpanContext)  // an explicit parent
                     .withTag("user_agent", req.UserAgent)
                     .withTag("lucky_number", 42)
                     .start();
   span.setTag("...", "...");

   // It is possible to set the Span as the active instance for the current context
   // (usually a thread).
   try (Scope scope = tracer.activateSpan(span)) {
      ...
   }
 

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

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

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, null otherwise.

See Also:

Format, Format.Builtin

close

void close()

Closes the Tracer, and tries to flush the in-memory collection to the configured persistance store.

The close method should be considered idempotent; closing an already closed Tracer should not raise an error. Spans that are created or finished after a Tracer has been closed may or may not be flushed. Calling the close method should be considered a synchronous operation. Observe this call may block for a relatively long period of time, depending on the internal shutdown.

For stateless tracers, this can be a no-op.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable