public final class Tracer extends Object
Span twoPhase = tracer.newTrace().name("twoPhase").start();
try {
Span prepare = tracer.newChild(twoPhase.context()).name("prepare").start();
try {
prepare();
} finally {
prepare.finish();
}
Span commit = tracer.newChild(twoPhase.context()).name("commit").start();
try {
commit();
} finally {
commit.finish();
}
} finally {
twoPhase.finish();
}
Span
,
Propagation
Modifier and Type | Class | Description |
---|---|---|
static class |
Tracer.Builder |
Deprecated.
Please use
Tracing.Builder |
static class |
Tracer.SpanInScope |
A span remains in the scope it was bound to until close is called.
|
Modifier and Type | Method | Description |
---|---|---|
Clock |
clock() |
Deprecated.
|
Span |
currentSpan() |
Returns the current span in scope or null if there isn't one.
|
Span |
joinSpan(TraceContext context) |
Joining is re-using the same trace and span ids extracted from an incoming RPC request.
|
static Tracer.Builder |
newBuilder() |
Deprecated.
Please use
Tracing.newBuilder() |
Span |
newChild(TraceContext parent) |
Explicitly creates a child within an existing trace.
|
Span |
newTrace() |
Explicitly creates a new trace.
|
Span |
newTrace(SamplingFlags samplingFlags) |
Like
newTrace() , but supports parameterized sampling, for example limiting on
operation or url pattern. |
Span |
nextSpan() |
Returns a new child span if there's a
currentSpan() or a new trace if there isn't. |
Span |
nextSpan(TraceContextOrSamplingFlags extracted) |
This creates a new span based on parameters extracted from an incoming request.
|
Span |
toSpan(TraceContext context) |
Converts the context as-is to a Span object
|
String |
toString() |
|
Tracer.SpanInScope |
withSpanInScope(Span span) |
Makes the given span the "current span" and returns an object that exits that scope on close.
|
@Deprecated public static Tracer.Builder newBuilder()
Tracing.newBuilder()
@Deprecated public Clock clock()
Tracing.clock(TraceContext)
public Span newTrace()
To implicitly create a new trace, or a span within an existing one, use nextSpan()
.
public final Span joinSpan(TraceContext context)
nextSpan(TraceContextOrSamplingFlags)
is a better choice.
When this incoming context is sampled, we assume this is a shared span, one where the caller and the current tracer report to the same span IDs. If no sampling decision occurred yet, we have exclusive access to this span ID.
Here's an example of conditionally joining a span, depending on if a trace context was extracted from an incoming request.
extracted = extractor.extract(request);
span = contextOrFlags.context() != null
? tracer.joinSpan(contextOrFlags.context())
: tracer.nextSpan(extracted);
Note: When Propagation.Factory.supportsJoin()
is false, this will always
fork a new child via newChild(TraceContext)
.
public Span newChild(TraceContext parent)
To implicitly create a new trace, or a span within an existing one, use nextSpan()
.
public Span nextSpan(TraceContextOrSamplingFlags extracted)
nextSpan()
. If a sampling decision
has not yet been made, one will happen here.
Ex.
extracted = extractor.extract(request);
span = tracer.nextSpan(extracted);
Note: Unlike joinSpan(TraceContext)
, this does not attempt to re-use
extracted span IDs. This means the extracted context (if any) is the parent of the span
returned.
Note: If a context could be extracted from the input, that trace is resumed, not
whatever the currentSpan()
was. Make sure you re-apply withSpanInScope(Span)
so that data is written to the correct trace.
public Span newTrace(SamplingFlags samplingFlags)
newTrace()
, but supports parameterized sampling, for example limiting on
operation or url pattern.
For example, to sample all requests for a specific url:
Span newTrace(Request input) {
SamplingFlags flags = SamplingFlags.NONE;
if (input.url().startsWith("/experimental")) {
flags = SamplingFlags.SAMPLED;
} else if (input.url().startsWith("/static")) {
flags = SamplingFlags.NOT_SAMPLED;
}
return tracer.newTrace(flags);
}
public Span toSpan(TraceContext context)
public Tracer.SpanInScope withSpanInScope(@Nullable Span span)
currentSpan()
until the return value is closed.
The most convenient way to use this method is via the try-with-resources idiom. Ex.
// Assume a framework interceptor uses this method to set the inbound span as current
try (SpanInScope ws = tracer.withSpanInScope(span)) {
return inboundRequest.invoke();
} finally {
span.finish();
}
// An unrelated framework interceptor can now lookup the correct parent for an outbound
request
Span parent = tracer.currentSpan()
Span span = tracer.nextSpan().name("outbound").start(); // parent is implicitly looked up
try (SpanInScope ws = tracer.withSpanInScope(span)) {
return outboundRequest.invoke();
} finally {
span.finish();
}
Note: While downstream code might affect the span, calling this method, and calling close on the result have no effect on the input. For example, calling close on the result does not finish the span. Not only is it safe to call close, you must call close to end the scope, or risk leaking resources associated with the scope.
span
- span to place into scope or null to clear the scope@Nullable public Span currentSpan()
public Span nextSpan()
currentSpan()
or a new trace if there isn't.Copyright © 2018 OpenZipkin. All rights reserved.