SpanCustomizer
public abstract class Span extends Object implements SpanCustomizer
// Note span methods chain. Explicitly start the span when ready.
Span span = tracer.nextSpan().name("encode").start();
// A span is not responsible for making itself current (scoped); the tracer is
try (SpanInScope ws = tracer.withSpanInScope(span)) {
return encoder.encode();
} catch (RuntimeException | Error e) {
span.error(e); // Unless you handle exceptions, you might not know the operation failed!
throw e;
} finally {
span.finish(); // finish - start = the duration of the operation in microseconds
}
This captures duration of start()
until finish()
is called.
Note: All methods return Span for chaining, but the instance is always the same.
Also, when only tracing in-process operations, consider ScopedSpan
: a simpler api.
Modifier and Type | Class | Description |
---|---|---|
static class |
Span.Kind |
Modifier and Type | Method | Description |
---|---|---|
abstract void |
abandon() |
Throws away the current span without reporting it.
|
abstract Span |
annotate(long timestamp,
String value) |
Like
annotate(String) , except with a given timestamp in microseconds. |
abstract Span |
annotate(String value) |
Associates an event that explains latency with the current system time.
|
abstract TraceContext |
context() |
|
abstract SpanCustomizer |
customizer() |
Returns a customizer appropriate for the current span.
|
abstract Span |
error(Throwable throwable) |
Adds tags depending on the configured
error parser |
abstract void |
finish() |
Reports the span complete, assigning the most precise duration possible.
|
abstract void |
finish(long timestamp) |
Like
finish() , except with a given timestamp in microseconds. |
abstract void |
flush() |
Reports the span, even if unfinished.
|
abstract boolean |
isNoop() |
When true, no recording is done and nothing is reported to zipkin.
|
abstract Span |
kind(Span.Kind kind) |
The kind of span is optional.
|
abstract Span |
name(String name) |
Sets the string name for the logical operation this span represents.
|
Span |
remoteEndpoint(zipkin2.Endpoint endpoint) |
Deprecated.
Use
remoteServiceName(String) remoteIpAndPort(String, int) .
Will be removed in Brave v6. |
abstract boolean |
remoteIpAndPort(String remoteIp,
int remotePort) |
Sets the IP and port associated with the remote endpoint.
|
abstract Span |
remoteServiceName(String remoteServiceName) |
Lower-case label of the remote node in the service graph, such as "favstar".
|
abstract Span |
start() |
Starts the span with an implicit timestamp.
|
abstract Span |
start(long timestamp) |
Like
start() , except with a given timestamp in microseconds. |
abstract Span |
tag(String key,
String value) |
Tags give your span context for search, viewing and analysis.
|
public abstract boolean isNoop()
public abstract TraceContext context()
public abstract SpanCustomizer customizer()
public abstract Span start()
Spans can be modified before calling start. For example, you can add tags to the span and set its name without lock contention.
public abstract Span start(long timestamp)
start()
, except with a given timestamp in microseconds.
Take extreme care with this feature as it is easy to have incorrect timestamps. If you must
use this, generate the timestamp using Tracing.clock(TraceContext)
.
public abstract Span name(String name)
name
in interface SpanCustomizer
public abstract Span kind(Span.Kind kind)
Span.Kind.SERVER
, the span's start timestamp is implicitly annotated as "sr" and
that plus its duration as "ss".public abstract Span annotate(String value)
annotate
in interface SpanCustomizer
value
- A short tag indicating the event, like "finagle.retry"public abstract Span annotate(long timestamp, String value)
annotate(String)
, except with a given timestamp in microseconds.
Take extreme care with this feature as it is easy to have incorrect timestamps. If you must
use this, generate the timestamp using Tracing.clock(TraceContext)
.
public abstract Span tag(String key, String value)
tag
in interface SpanCustomizer
key
- Name used to lookup spans, such as "your_app.version".value
- String value, cannot be null
.public abstract Span error(Throwable throwable)
error parser
@Deprecated public Span remoteEndpoint(zipkin2.Endpoint endpoint)
remoteServiceName(String)
remoteIpAndPort(String, int)
.
Will be removed in Brave v6.public abstract Span remoteServiceName(String remoteServiceName)
This is a primary label for trace lookup and aggregation, so it should be intuitive and consistent. Many use a name from service discovery.
remoteIpAndPort(String, int)
public abstract boolean remoteIpAndPort(@Nullable String remoteIp, int remotePort)
Invalid inputs, such as hostnames, will return false. Port is only set with a valid IP, and zero or negative port values are ignored. For example, to set only the IP address, leave port as zero.
This returns boolean, not Span as it is often the case strings are malformed. Using this, you can do conditional parsing like so:
if (span.remoteIpAndPort(address.getHostAddress(), target.getPort())) return;
span.remoteIpAndPort(address.getHostName(), target.getPort());
Note: Comma separated lists are not supported. If you have multiple entries choose the one most indicative of the remote side. For example, the left-most entry in X-Forwarded-For.
remoteIp
- the IPv4 or IPv6 literal representing the remote service connectionremotePort
- the port associated with the IP, or zero if unknown.remoteServiceName(String)
public abstract void finish()
public abstract void abandon()
public abstract void finish(long timestamp)
finish()
, except with a given timestamp in microseconds.
Zipkin's span duration
is derived by subtracting the start
timestamp from this, and set when appropriate.
Take extreme care with this feature as it is easy to have incorrect timestamps. If you must
use this, generate the timestamp using Tracing.clock(TraceContext)
.
public abstract void flush()
This primarily supports two use cases: one-way spans and orphaned spans. For example, a one-way span can be modeled as a span where one tracer calls start and another calls finish. In order to report that span from its origin, flush must be called.
Another example is where a user didn't call finish within a deadline or before a shutdown occurs. By flushing, you can report what was in progress.
Copyright © 2018 OpenZipkin. All rights reserved.