Package 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	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	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 RPC request.
static Tracer.Builder	newBuilder()	Deprecated. Please use Tracing.newBuilder()
Span	newChild(TraceContext parent)	Explicitly creates a child within an existing.
Span	newTrace()	Explicitly 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	nextSpan(TraceContextOrSamplingFlags extracted)	This creates a new span based on parameters extracted from an incoming request.
Span	toSpan(TraceContext context)	Converts the context as-is to a Span object
String	toString()
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, 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()

Explicitly creates a new trace. The result will be a root span (no parent span ID).

To implicitly create a new trace, or a span within an existing one, use nextSpan().

joinSpan

public final Span joinSpan(TraceContext context)

Joining is re-using the same trace and span ids extracted from an incoming RPC request. This should not be used for messaging operations, as nextSpan(TraceContextOrSamplingFlags) is a better choice.

When this incoming context is sampled, 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.

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

Note: When Propagation.Factory.supportsJoin() is false, this will always fork a new child via newChild(TraceContext).

See Also:

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

newChild

public Span newChild(TraceContext parent)

Explicitly creates a child within an existing. The result will be have its parent ID set to the input's span ID.

To implicitly create a new trace, or a span within an existing one, use nextSpan().

nextSpan

public Span nextSpan(TraceContextOrSamplingFlags extracted)

This creates a new span based on parameters extracted from an incoming request. This will always result in a new span. If no trace identifiers were extracted, a span will be created based on the implicit context in the same manner as nextSpan().

Ex.

 extracted = extractor.extract(request);
 span = tracer.nextSpan(extracted);
 

Note: Unlike joinSpan(TraceContext), this does not attempt to re-use extracted span IDs. This means the extracted context (if any) is the parent of the span returned.

Note: If a context could be extracted from the input, that trace is resumed, not whatever the currentSpan() was. Make sure you re-apply withSpanInScope(Span) so that data is written to the correct trace.

See Also:

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

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

withSpanInScope

public Tracer.SpanInScope withSpanInScope(@Nullable
                                          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.

Parameters:

span - span to place into scope or null to clear the scope

currentSpan

@Nullable
public Span currentSpan()

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

nextSpan

public Span nextSpan()

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

toString

public String toString()

Overrides:

toString in class Object