Module brave
Package brave

Class ScopedSpan

  • public abstract class ScopedSpan
extends java.lang.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 Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      abstract ScopedSpan annotate​(java.lang.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​(java.lang.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​(java.lang.String key, java.lang.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​(java.lang.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​(java.lang.String key,
                               java.lang.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​(java.lang.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.