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: All methods return ScopedSpan for chaining, but the instance is always the same. Also, this type is intended for in-process synchronous code. Do not leak this onto another thread: it is not thread-safe. For advanced features or remote commands, use Span instead.

  • Method Details

    • 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.