Package brave

Class ScopedSpan

java.lang.Object

brave.ScopedSpan

public abstract class ScopedSpan
extends Object

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

 // Note span methods chain. Explicitly start the span when ready.
 ScopedSpan span = tracer.startScopedSpan("encode");
 try {
   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
 }
 

Usage notes: this type is intended for in-process synchronous code. Do not leak this type onto another thread: it is not thread-safe. For advanced features or remote commands, use Span.

Method Summary

Modifier and Type	Method	Description
abstract ScopedSpan	annotate(String value)	Associates an event that explains latency with the current system time.
abstract TraceContext	context()	Returns the trace context associated with this span
abstract ScopedSpan	error(Throwable throwable)	Adds tags depending on the configured error parser
abstract void	finish()	Closes the scope associated with this span, then reports the span complete, assigning the most precise duration possible.
abstract boolean	isNoop()	When true, no recording will take place, so no data is reported on finish.
abstract ScopedSpan	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 will take place, so no data is reported on finish. However, the trace context is in scope until finish() is called.

context

public abstract TraceContext context()

Returns the trace context associated with this span

annotate

public abstract ScopedSpan annotate(String value)

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

Parameters:

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

tag

public abstract ScopedSpan 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.

Parameters:

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

value - String value, cannot be null.

error

public abstract ScopedSpan error(Throwable throwable)

Adds tags depending on the configured error parser

finish

public abstract void finish()

Closes the scope associated with this span, then reports the span complete, assigning the most precise duration possible.