Package brave

Class Span

java.lang.Object

brave.Span

All Implemented Interfaces:

SpanCustomizer

public abstract class Span
extends Object
implements SpanCustomizer

Used to model the latency of an operation. Here's a typical example of synchronous tracing from perspective of the span:

 // 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: When only tracing in-process operations, consider ScopedSpan: a simpler api.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Span.Kind

Method Summary

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.
abstract Span	remoteEndpoint(zipkin2.Endpoint endpoint)	For a client span, this would be the server's address.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isNoop

public abstract boolean isNoop()

When true, no recording is done and nothing is reported to zipkin. However, this span should still be injected into outgoing requests. Use this flag to avoid performing expensive computation.

context

public abstract TraceContext context()

customizer

public abstract SpanCustomizer customizer()

Returns a customizer appropriate for the current span. Prefer this when invoking user code

start

public abstract Span start()

Starts the span with an implicit timestamp.

Spans can be modified before calling start. For example, you can add tags to the span and set its name without lock contention.

start

public abstract Span start(long timestamp)

Like 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).

name

public abstract Span name(String name)

Sets the string name for the logical operation this span represents.

Specified by:

name in interface SpanCustomizer

kind

public abstract Span kind(Span.Kind kind)

The kind of span is optional. When set, it affects how a span is reported. For example, if the kind is Span.Kind.SERVER, the span's start timestamp is implicitly annotated as "sr" and that plus its duration as "ss".

annotate

public abstract Span annotate(String value)

Associates an event that explains latency with the current system time.

Specified by:

annotate in interface SpanCustomizer

Parameters:

value - A short tag indicating the event, like "finagle.retry"

annotate

public abstract Span annotate(long timestamp,
                              String value)

Like 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).

tag

public abstract Span tag(String key,
                         String value)

Tags give your span context for search, viewing and analysis. For example, a key "your_app.version" would let you lookup spans by version. A tag "sql.query" isn't searchable, but it can help in debugging when viewing a trace.

Specified by:

tag in interface SpanCustomizer

Parameters:

key - Name used to lookup spans, such as "your_app.version".

value - String value, cannot be null.

error

public abstract Span error(Throwable throwable)

Adds tags depending on the configured error parser

remoteEndpoint

public abstract Span remoteEndpoint(zipkin2.Endpoint endpoint)

For a client span, this would be the server's address.

It is often expensive to derive a remote address: always check isNoop() first!

finish

public abstract void finish()

Reports the span complete, assigning the most precise duration possible.

abandon

public abstract void abandon()

Throws away the current span without reporting it.

finish

public abstract void finish(long timestamp)

Like 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).

flush

public abstract void flush()

Reports the span, even if unfinished. Most users will not call this method.

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.