@ThreadSafe
public interface Tracer
Span
creation and interaction with the in-process context.
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 = OpenTelemetry.getTracer();
void doWork() {
Span span = tracer.spanBuilder("MyClass.DoWork").startSpan();
try(Scope ss = tracer.withSpan(span)) {
tracer.getCurrentSpan().addEvent("Starting the work.");
doWorkInternal();
tracer.getCurrentSpan().addEvent("Finished working.");
} finally {
span.end();
}
}
}
Example usage with manual context propagation:
class MyClass {
private static final Tracer tracer = OpenTelemetry.getTracer();
void doWork(Span parent) {
Span childSpan = tracer.spanBuilder("MyChildSpan")
setParent(parent).startSpan();
childSpan.addEvent("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 and Type | Method and Description |
---|---|
Span |
getCurrentSpan()
Gets the current Span from the current Context.
|
Span.Builder |
spanBuilder(java.lang.String spanName)
Returns a
Span.Builder to create and start a new Span . |
io.opentelemetry.context.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. |
Span getCurrentSpan()
To install a Span
to the current Context use withSpan(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 io.opentelemetry.context.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 DefaultSpan
to enter a scope of code where tracing is stopped.
Example of usage:
private static Tracer tracer = OpenTelemetry.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().addEvent("my event");
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 = OpenTelemetry.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().addEvent("my event");
doSomeOtherWork(); // Here "span" is the current Span.
} finally {
ws.close();
}
span.end();
}
Span.Builder spanBuilder(java.lang.String spanName)
spanName
- The name of the returned Span.Span.Builder
to create and start a new Span
.java.lang.NullPointerException
- if spanName
is null
.