brave

Class Tracer

java.lang.Object

brave.Tracer

public final class Tracer
extends Object

Using a tracer, you can create a root span capturing the critical path of a request. Child spans can be created to allocate latency relating to outgoing requests. Here's a contrived example:

 Span twoPhase = tracer.newTrace().name("twoPhase").start();
 try {
   Span prepare = tracer.newChild(twoPhase.context()).name("prepare").start();
   try {
     prepare();
   } finally {
     prepare.finish();
   }
   Span commit = tracer.newChild(twoPhase.context()).name("commit").start();
   try {
     commit();
   } finally {
     commit.finish();
   }
 } finally {
   twoPhase.finish();
 }
 

See Also:

Span, Propagation

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Tracer.Builder Deprecated. Please use Tracing.Builder
static class	Tracer.SpanInScope A span remains in the scope it was bound to until close is called.

Method Summary

Modifier and Type	Method and Description
Clock	clock() Deprecated. use Tracing.clock()
Span	currentSpan() Returns the current span in scope or null if there isn't one.
Span	joinSpan(TraceContext context) Joining is re-using the same trace and span ids extracted from an incoming request.
static Tracer.Builder	newBuilder() Deprecated. Please use Tracing.newBuilder()
Span	newChild(TraceContext parent) Creates a new span within an existing trace.
Span	newTrace() Creates a new trace.
Span	newTrace(SamplingFlags samplingFlags) Like newTrace(), but supports parameterized sampling, for example limiting on operation or url pattern.
Span	nextSpan() Returns a new child span if there's a currentSpan() or a new trace if there isn't.
Span	toSpan(TraceContext context) Converts the context as-is to a Span object
Tracer.SpanInScope	withSpanInScope(Span span) Makes the given span the "current span" and returns an object that exits that scope on close.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newBuilder

@Deprecated
public static Tracer.Builder newBuilder()

Deprecated. Please use Tracing.newBuilder()

clock

@Deprecated
public Clock clock()

Deprecated. use Tracing.clock()

newTrace

public Span newTrace()

Creates a new trace. If there is an existing trace, use newChild(TraceContext) instead.

joinSpan

public final Span joinSpan(TraceContext context)

Joining is re-using the same trace and span ids extracted from an incoming request. Here, we ensure a sampling decision has been made. If the span passed sampling, we assume this is a shared span, one where the caller and the current tracer report to the same span IDs. If no sampling decision occurred yet, we have exclusive access to this span ID.

Here's an example of conditionally joining a span, depending on if a trace context was extracted from an incoming request.

 contextOrFlags = extractor.extract(request);
 span = contextOrFlags.context() != null
          ? tracer.joinSpan(contextOrFlags.context())
          : tracer.newTrace(contextOrFlags.samplingFlags());
 

See Also:

Propagation, TraceContext.Extractor#extract(Object), TraceContextOrSamplingFlags.context()

newTrace

public Span newTrace(SamplingFlags samplingFlags)

Like newTrace(), but supports parameterized sampling, for example limiting on operation or url pattern.

For example, to sample all requests for a specific url:

 Span newTrace(Request input) {
   SamplingFlags flags = SamplingFlags.NONE;
   if (input.url().startsWith("/experimental")) {
     flags = SamplingFlags.SAMPLED;
   } else if (input.url().startsWith("/static")) {
     flags = SamplingFlags.NOT_SAMPLED;
   }
   return tracer.newTrace(flags);
 }
 

toSpan

public Span toSpan(TraceContext context)

Converts the context as-is to a Span object

newChild

public Span newChild(TraceContext parent)

Creates a new span within an existing trace. If there is no existing trace, use newTrace() instead.

withSpanInScope

public Tracer.SpanInScope withSpanInScope(Span span)

Makes the given span the "current span" and returns an object that exits that scope on close. The span provided will be returned by currentSpan() until the return value is closed.

The most convenient way to use this method is via the try-with-resources idiom. Ex.

 // Assume a framework interceptor uses this method to set the inbound span as current
 try (SpanInScope ws = tracer.withSpanInScope(span)) {
   return inboundRequest.invoke();
 } finally {
   span.finish();
 }

 // An unrelated framework interceptor can now lookup the correct parent for an outbound
 request
 Span parent = tracer.currentSpan()
 Span span = tracer.nextSpan().name("outbound").start(); // parent is implicitly looked up
 try (SpanInScope ws = tracer.withSpanInScope(span)) {
   return outboundRequest.invoke();
 } finally {
   span.finish();
 }
 

Note: While downstream code might affect the span, calling this method, and calling close on the result have no effect on the input. For example, calling close on the result does not finish the span. Not only is it safe to call close, you must call close to end the scope, or risk leaking resources associated with the scope.

currentSpan

@Nullable
public Span currentSpan()

Returns the current span in scope or null if there isn't one.

nextSpan

@Nullable
public Span nextSpan()

Returns a new child span if there's a currentSpan() or a new trace if there isn't.