Package brave

Class ScopedSpan

java.lang.Object
brave.ScopedSpan
All Implemented Interfaces:
SpanCustomizer
public abstract class ScopedSpan
extends Object
implements SpanCustomizer
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.
Since:
4.19

  • 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.
      Since:
      4.19

    • context

      public abstract TraceContext context()
      Returns the trace context associated with this span
      Since:
      4.19

    • name

      public abstract ScopedSpan name​(String name)
      Sets the string name for the logical operation this span represents.
      Specified by:
      name in interface SpanCustomizer
      Since:
      5.11

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

      Note:To guard potentially expensive parsing, implement Tag instead, which avoids parsing into a no-op span.

      Ex. 

      {@code
 SUMMARY_TAG = new Tag("summary") {
      Specified by:
      tag in interface SpanCustomizer
      Parameters:
      key - Name used to lookup spans, such as "your_app.version".
      value - String value, cannot be null.
      Since:
      4.19
      See Also:
      Tag.tag(Object, SpanCustomizer)

    • annotate

      public abstract ScopedSpan 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"
      Since:
      4.19

    • error

      public abstract ScopedSpan error​(Throwable throwable)
      Records an error that impacted this operation.

      Note: Calling this does not finish the span.

      Since:
      4.19

    • finish

      public abstract void finish()
      Closes the scope associated with this span, then reports the span complete, assigning the most precise duration possible.
      Since:
      4.19