io.opencensus.trace

Class Tracer

java.lang.Object

io.opencensus.trace.Tracer

public abstract class Tracer
extends Object

Tracer is a simple, thin class for Span creation and in-process context interaction.

Users may choose to use manual or automatic Context propagation. Because of that this class offers APIs to facilitate both usages.

The automatic context propagation is done using Context which is a gRPC independent implementation for in-process Context propagation mechanism which can carry scoped-values across API boundaries and between threads. Users of the library must propagate the Context between different threads.

Example usage with automatic context propagation:

 class MyClass {
   private static final Tracer tracer = Tracing.getTracer();
   void doWork() {
     try(Scope ss = tracer.spanBuilder("MyClass.DoWork").startScopedSpan) {
       tracer.getCurrentSpan().addAnnotation("Starting the work.");
       doWorkInternal();
       tracer.getCurrentSpan().addAnnotation("Finished working.");
     }
   }
 }
 

Example usage with manual context propagation:

 class MyClass {
   private static final Tracer tracer = Tracing.getTracer();
   void doWork(Span parent) {
     Span childSpan = tracer.spanBuilderWithExplicitParent("MyChildSpan", parent).startSpan();
     childSpan.addAnnotation("Starting the work.");
     try {
       doSomeWork(childSpan); // Manually propagate the new span down the stack.
     } finally {
       // To make sure we end the span even in case of an exception.
       childSpan.end();  // Manually end the span.
     }
   }
 }
 

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Tracer()

Method Summary

Modifier and Type	Method and Description
Span	getCurrentSpan() Gets the current Span from the current Context.
SpanBuilder	spanBuilder(String spanName) Returns a SpanBuilder to create and start a new child Span as a child of to the current Span if any, otherwise creates a root Span.
abstract SpanBuilder	spanBuilderWithExplicitParent(String spanName, Span parent) Returns a SpanBuilder to create and start a new child Span (or root if parent is null or has an invalid SpanContext), with parent being the designated Span.
abstract SpanBuilder	spanBuilderWithRemoteParent(String spanName, SpanContext remoteParentSpanContext) Returns a SpanBuilder to create and start a new child Span (or root if parent is SpanContext.INVALID or null), with parent being the remote Span designated by the SpanContext.
Scope	withSpan(Span span) Enters the scope of code where the given Span is in the current Context, and returns an object that represents that scope.
<C> Callable<C>	withSpan(Span span, Callable<C> callable) Returns a Callable that runs the given task with the given Span in the current context.
Runnable	withSpan(Span span, Runnable runnable) Returns a Runnable that runs the given task with the given Span in the current context.

Methods inherited from class java.lang.Object

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

Constructor Detail

Tracer

protected Tracer()

Method Detail

getCurrentSpan

public final Span getCurrentSpan()

Gets the current Span from the current Context.

To install a Span to the current Context use withSpan(Span) OR use SpanBuilder.startScopedSpan() methods to start a new Span.

startSpan methods do NOT modify the current Context Span.

Returns:

a default Span that does nothing and has an invalid SpanContext if no Span is associated with the current Context, otherwise the current Span from the Context.

withSpan

@MustBeClosed
public final Scope withSpan(Span span)

Enters the scope of code where the given Span is in the current Context, and returns an object that represents that scope. The scope is exited when the returned object is closed.

Supports try-with-resource idiom.

Can be called with BlankSpan to enter a scope of code where tracing is stopped.

Example of usage:

 private static Tracer tracer = Tracing.getTracer();
 void doWork() {
   // Create a Span as a child of the current Span.
   Span span = tracer.spanBuilder("my span").startSpan();
   try (Scope ws = tracer.withSpan(span)) {
     tracer.getCurrentSpan().addAnnotation("my annotation");
     doSomeOtherWork();  // Here "span" is the current Span.
   }
   span.end();
 }
 

Prior to Java SE 7, you can use a finally block to ensure that a resource is closed regardless of whether the try statement completes normally or abruptly.

Example of usage prior to Java SE7:

 private static Tracer tracer = Tracing.getTracer();
 void doWork() {
   // Create a Span as a child of the current Span.
   Span span = tracer.spanBuilder("my span").startSpan();
   Scope ws = tracer.withSpan(span);
   try {
     tracer.getCurrentSpan().addAnnotation("my annotation");
     doSomeOtherWork();  // Here "span" is the current Span.
   } finally {
     ws.close();
   }
   span.end();
 }
 

Parameters:

span - The Span to be set to the current Context.

Returns:

an object that defines a scope where the given Span will be set to the current Context.

Throws:

NullPointerException - if span is null.

withSpan

public final Runnable withSpan(Span span,
                               Runnable runnable)

Returns a Runnable that runs the given task with the given Span in the current context.

Users may consider to use SpanBuilder.startSpanAndRun(Runnable).

Any error will end up as a Status.UNKNOWN.

IMPORTANT: Caller must manually propagate the entire io.grpc.Context when wraps a Runnable, see the examples.

IMPORTANT: Caller must manually end the Span within the Runnable, or after the Runnable is executed.

Example with Executor wrapped with Context.currentContextExecutor(java.util.concurrent.Executor):

 class MyClass {
   private static Tracer tracer = Tracing.getTracer();
   void handleRequest(Executor executor) {
     Span span = new Tracer.spanBuilder("MyRunnableSpan");
     executor.execute(tracer.withSpan(span, new Runnable() {
       @Override
       public void run() {
         try {
           sendResult();
         } finally {
           span.end();
         }
       }
     }));
   }
 }
 

Example without Executor wrapped with Context.currentContextExecutor(java.util.concurrent.Executor):

 class MyClass {
   private static Tracer tracer = Tracing.getTracer();
   void handleRequest(Executor executor) {
     Span span = new Tracer.spanBuilder("MyRunnableSpan");
     executor.execute(Context.wrap(tracer.withSpan(span, new Runnable() {
       @Override
       public void run() {
         try {
           sendResult();
         } finally {
           span.end();
         }
       }
     })));
   }
 }
 

Parameters:

span - the Span to be set as current.

runnable - the Runnable to withSpan in the Span.

Returns:

the Runnable.

Since:

0.11.0

withSpan

public final <C> Callable<C> withSpan(Span span,
                                      Callable<C> callable)

Returns a Callable that runs the given task with the given Span in the current context.

Users may consider to use SpanBuilder.startSpanAndCall(Callable).

Any error will end up as a Status.UNKNOWN.

IMPORTANT: Caller must manually propagate the entire io.grpc.Context when wraps a Callable, see the examples.

IMPORTANT: Caller must manually end the Span within the Callable, or after the Callable is executed.

Example with Executor wrapped with Context.currentContextExecutor(java.util.concurrent.Executor):

 class MyClass {
   private static Tracer tracer = Tracing.getTracer();
   void handleRequest(Executor executor) {
     Span span = new Tracer.spanBuilder("MyRunnableSpan");
     executor.execute(tracer.withSpan(span,  new Callable<MyResult>() {
       @Override
       public MyResult call() throws Exception {
         try {
           return sendResult();
         } finally {
           span.end();
         }
       }
     }));
   }
 }
 

Example without Executor wrapped with Context.currentContextExecutor(java.util.concurrent.Executor):

 class MyClass {
   private static Tracer tracer = Tracing.getTracer();
   void handleRequest(Executor executor) {
     Span span = new Tracer.spanBuilder("MyRunnableSpan");
     executor.execute(Context.wrap(tracer.withSpan(span,  new Callable<MyResult>() {
       @Override
       public MyResult call() throws Exception {
         try {
           return sendResult();
         } finally {
           span.end();
         }
       }
     })));
   }
 }
 

Parameters:

span - the Span to be set as current.

callable - the Callable to run in the Span.

Returns:

the Callable.

Since:

0.11.0

spanBuilder

public final SpanBuilder spanBuilder(String spanName)

Returns a SpanBuilder to create and start a new child Span as a child of to the current Span if any, otherwise creates a root Span.

See SpanBuilder for usage examples.

This must be used to create a Span when automatic Context propagation is used.

This is equivalent with:

 tracer.spanBuilderWithExplicitParent("MySpanName",tracer.getCurrentSpan());
 

Parameters:

spanName - The name of the returned Span.

Returns:

a SpanBuilder to create and start a new Span.

Throws:

NullPointerException - if spanName is null.

spanBuilderWithExplicitParent

public abstract SpanBuilder spanBuilderWithExplicitParent(String spanName,
                                                          @Nullable
                                                          Span parent)

Returns a SpanBuilder to create and start a new child Span (or root if parent is null or has an invalid SpanContext), with parent being the designated Span.

See SpanBuilder for usage examples.

This must be used to create a Span when manual Context propagation is used OR when creating a root Span with a null parent.

Parameters:

spanName - The name of the returned Span.

parent - The parent of the returned Span. If null the SpanBuilder will build a root Span.

Returns:

a SpanBuilder to create and start a new Span.

Throws:

NullPointerException - if spanName is null.

spanBuilderWithRemoteParent

public abstract SpanBuilder spanBuilderWithRemoteParent(String spanName,
                                                        @Nullable
                                                        SpanContext remoteParentSpanContext)

Returns a SpanBuilder to create and start a new child Span (or root if parent is SpanContext.INVALID or null), with parent being the remote Span designated by the SpanContext.

See SpanBuilder for usage examples.

This must be used to create a Span when the parent is in a different process. This is only intended for use by RPC systems or similar.

If no SpanContext OR fail to parse the SpanContext on the server side, users must call this method with a null remote parent SpanContext.

Parameters:

spanName - The name of the returned Span.

remoteParentSpanContext - The remote parent of the returned Span.

Returns:

a SpanBuilder to create and start a new Span.

Throws:

NullPointerException - if spanName is null.