Class Tracer
- java.lang.Object
-
- io.opencensus.trace.Tracer
-
- Direct Known Subclasses:
Tracer.NoopTracer
,TracerImpl
public abstract class Tracer extends java.lang.Object
Tracer is a simple, thin class forSpan
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 theContext
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. } } }
- Since:
- 0.5
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
Tracer.NoopTracer
-
Field Summary
Fields Modifier and Type Field Description private static Tracer.NoopTracer
noopTracer
-
Constructor Summary
Constructors Modifier Constructor Description protected
Tracer()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description Span
getCurrentSpan()
Gets the current Span from the current Context.(package private) static Tracer
getNoopTracer()
Returns the no-op implementation of theTracer
.SpanBuilder
spanBuilder(java.lang.String spanName)
Returns aSpanBuilder
to create and start a new childSpan
as a child of to the currentSpan
if any, otherwise creates a rootSpan
.abstract SpanBuilder
spanBuilderWithExplicitParent(java.lang.String spanName, Span parent)
Returns aSpanBuilder
to create and start a new childSpan
(or root if parent isnull
or has an invalidSpanContext
), with parent being the designatedSpan
.abstract SpanBuilder
spanBuilderWithRemoteParent(java.lang.String spanName, SpanContext remoteParentSpanContext)
Returns aSpanBuilder
to create and start a new childSpan
(or root if parent isSpanContext.INVALID
ornull
), with parent being the remoteSpan
designated by theSpanContext
.Scope
withSpan(Span span)
Enters the scope of code where the givenSpan
is in the current Context, and returns an object that represents that scope.java.lang.Runnable
withSpan(Span span, java.lang.Runnable runnable)
Returns aRunnable
that runs the given task with the givenSpan
in the current context.<C> java.util.concurrent.Callable<C>
withSpan(Span span, java.util.concurrent.Callable<C> callable)
Returns aCallable
that runs the given task with the givenSpan
in the current context.
-
-
-
Field Detail
-
noopTracer
private static final Tracer.NoopTracer noopTracer
-
-
Method Detail
-
getNoopTracer
static Tracer getNoopTracer()
Returns the no-op implementation of theTracer
.- Returns:
- the no-op implementation of the
Tracer
.
-
getCurrentSpan
public final Span getCurrentSpan()
Gets the current Span from the current Context.To install a
Span
to the current Context usewithSpan(Span)
OR useSpanBuilder.startScopedSpan()
methods to start a newSpan
.startSpan methods do NOT modify the current Context
Span
.- Returns:
- a default
Span
that does nothing and has an invalidSpanContext
if noSpan
is associated with the current Context, otherwise the currentSpan
from the Context. - Since:
- 0.5
-
withSpan
@MustBeClosed public final Scope withSpan(Span span)
Enters the scope of code where the givenSpan
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(); }
-
withSpan
public final java.lang.Runnable withSpan(Span span, java.lang.Runnable runnable)
Returns aRunnable
that runs the given task with the givenSpan
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 aRunnable
, see the examples.IMPORTANT: Caller must manually end the
Span
within theRunnable
, or after theRunnable
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 = tracer.spanBuilder("MyRunnableSpan").startSpan(); 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 = tracer.spanBuilder("MyRunnableSpan").startSpan(); executor.execute(Context.wrap(tracer.withSpan(span, new Runnable() { @Override public void run() { try { sendResult(); } finally { span.end(); } } }))); } }
- Parameters:
span
- theSpan
to be set as current.runnable
- theRunnable
to withSpan in theSpan
.- Returns:
- the
Runnable
. - Since:
- 0.11.0
-
withSpan
public final <C> java.util.concurrent.Callable<C> withSpan(Span span, java.util.concurrent.Callable<C> callable)
Returns aCallable
that runs the given task with the givenSpan
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 aCallable
, see the examples.IMPORTANT: Caller must manually end the
Span
within theCallable
, or after theCallable
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 = tracer.spanBuilder("MyRunnableSpan").startSpan(); 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 = tracer.spanBuilder("MyRunnableSpan").startSpan(); executor.execute(Context.wrap(tracer.withSpan(span,
new Callable<MyResult>()
{ @Override public MyResult call() throws Exception { try { return sendResult(); } finally { span.end(); } } }))); } }- Parameters:
span
- theSpan
to be set as current.callable
- theCallable
to run in theSpan
.- Returns:
- the
Callable
. - Since:
- 0.11.0
-
spanBuilder
public final SpanBuilder spanBuilder(java.lang.String spanName)
Returns aSpanBuilder
to create and start a new childSpan
as a child of to the currentSpan
if any, otherwise creates a rootSpan
.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 newSpan
. - Throws:
java.lang.NullPointerException
- ifspanName
isnull
.- Since:
- 0.5
-
spanBuilderWithExplicitParent
public abstract SpanBuilder spanBuilderWithExplicitParent(java.lang.String spanName, @Nullable Span parent)
Returns aSpanBuilder
to create and start a new childSpan
(or root if parent isnull
or has an invalidSpanContext
), with parent being the designatedSpan
.See
SpanBuilder
for usage examples.This must be used to create a
Span
when manual Context propagation is used OR when creating a rootSpan
with anull
parent.- Parameters:
spanName
- The name of the returned Span.parent
- The parent of the returned Span. Ifnull
theSpanBuilder
will build a rootSpan
.- Returns:
- a
SpanBuilder
to create and start a newSpan
. - Throws:
java.lang.NullPointerException
- ifspanName
isnull
.- Since:
- 0.5
-
spanBuilderWithRemoteParent
public abstract SpanBuilder spanBuilderWithRemoteParent(java.lang.String spanName, @Nullable SpanContext remoteParentSpanContext)
Returns aSpanBuilder
to create and start a new childSpan
(or root if parent isSpanContext.INVALID
ornull
), with parent being the remoteSpan
designated by theSpanContext
.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 theSpanContext
on the server side, users must call this method with anull
remote parentSpanContext
.- Parameters:
spanName
- The name of the returned Span.remoteParentSpanContext
- The remote parent of the returned Span.- Returns:
- a
SpanBuilder
to create and start a newSpan
. - Throws:
java.lang.NullPointerException
- ifspanName
isnull
.- Since:
- 0.5
-
-