io.opentracing

Interface Tracer

public interface Tracer

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.

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 Span.setOperationName(String).

A contrived example:

    Tracer tracer = ...

    Span parentSpan = tracer.buildSpan("DoWork")
                            .start();

    Span http = tracer.buildSpan("HandleHTTPRequest")
                      .asChildOf(parentSpan.context())
                      .withTag("user_agent", req.UserAgent)
                      .withTag("lucky_number", 42)
                      .start();
    

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.

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