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(NonThrowingCloseable 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 span = tracer.spanBuilder(null, "MyRootSpan").startSpan();
span.addAnnotation("Starting the work.");
try {
doSomeWork(span); // Manually propagate the new span down the stack.
} finally {
span.addAnnotation("Finished working.");
// To make sure we end the span even in case of an exception.
span.end(); // Manually end the span.
}
}
}
| Modifier | Constructor and Description |
|---|---|
protected |
Tracer(SpanFactory spanFactory) |
| Modifier and Type | Method and Description |
|---|---|
Span |
getCurrentSpan()
Gets the current Span from the current Context.
|
SpanBuilder |
spanBuilder(Span parent,
String name)
Returns a
SpanBuilder to create and start a new child Span (or root if parent
is null), with parent being the designated Span. |
SpanBuilder |
spanBuilder(String name)
Returns a
SpanBuilder to create and start a new child Span as a child of to the
current Span if any, otherwise create a root Span with the default options. |
SpanBuilder |
spanBuilderWithRemoteParent(SpanContext remoteParent,
String name)
Returns a
SpanBuilder to create and start a new child Span (or root if parent
is null), with parent being the Span designated by the SpanContext. |
NonThrowingCloseable |
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. |
protected Tracer(SpanFactory spanFactory)
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.public final NonThrowingCloseable 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 (NonThrowingCloseable 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();
NonThrowingCloseable 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 SpanBuilder spanBuilder(String name)
SpanBuilder to create and start a new child Span as a child of to the
current Span if any, otherwise create a root Span with the default options.
See SpanBuilder for usage examples.
This must be used to create a Span when automatic Context propagation is
used.
name - The name of the returned Span.SpanBuilder to create and start a new Span.NullPointerException - if name is null.public final SpanBuilder spanBuilder(@Nullable Span parent, String name)
SpanBuilder to create and start a new child Span (or root if parent
is null), 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.
parent - The parent of the returned Span. If null the SpanBuilder will build a
root Span.name - The name of the returned Span.SpanBuilder to create and start a new Span.NullPointerException - if name is null.public final SpanBuilder spanBuilderWithRemoteParent(@Nullable SpanContext remoteParent, String name)
SpanBuilder to create and start a new child Span (or root if parent
is null), with parent being the 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.
remoteParent - The remote parent of the returned Span.name - The name of the returned Span.SpanBuilder to create and start a new Span.NullPointerException - if name is null.