Package brave

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