public abstract class Tracer extends Object
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.
}
}
}
Modifier | Constructor and Description |
---|---|
protected |
Tracer() |
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. |
public final Span getCurrentSpan()
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
.
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.@MustBeClosed public final Scope withSpan(Span span)
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();
}
span
- The Span
to be set to the current Context.Span
will be set to the current
Context.NullPointerException
- if span
is null
.public final Runnable withSpan(Span span, Runnable runnable)
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 = 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();
}
}
})));
}
}
span
- the Span
to be set as current.runnable
- the Runnable
to withSpan in the Span
.Runnable
.public final <C> Callable<C> withSpan(Span span, Callable<C> callable)
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 = 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();
}
}
})));
}
}
span
- the Span
to be set as current.callable
- the Callable
to run in the Span
.Callable
.public final SpanBuilder spanBuilder(String spanName)
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());
spanName
- The name of the returned Span.SpanBuilder
to create and start a new Span
.NullPointerException
- if spanName
is null
.public abstract SpanBuilder spanBuilderWithExplicitParent(String spanName, @Nullable Span parent)
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.
spanName
- The name of the returned Span.parent
- The parent of the returned Span. If null
the SpanBuilder
will
build a root Span
.SpanBuilder
to create and start a new Span
.NullPointerException
- if spanName
is null
.public abstract SpanBuilder spanBuilderWithRemoteParent(String spanName, @Nullable SpanContext remoteParentSpanContext)
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
.
spanName
- The name of the returned Span.remoteParentSpanContext
- The remote parent of the returned Span.SpanBuilder
to create and start a new Span
.NullPointerException
- if spanName
is null
.