Package brave

Class Span

  • All Implemented Interfaces:
    SpanCustomizer
    public abstract class Span
extends Object
implements SpanCustomizer
    Subtype of SpanCustomizer which can capture latency and remote context of an operation. Here's a typical example of synchronous tracing from perspective of the span: 
    
 // Note span methods chain. Explicitly start the span when ready.
 Span span = tracer.nextSpan().name("encode").start();
 // A span is not responsible for making itself current (scoped); the tracer is
 try (SpanInScope ws = tracer.withSpanInScope(span)) {
   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
 }

    This captures duration of start() until finish() is called.

    Usage notes

    All methods return Span for chaining, but the instance is always the same. Also, when only tracing in-process operations, consider ScopedSpan: a simpler api.

    • Method Detail

      • isNoop

        public abstract boolean isNoop()
        When true, no recording is done and nothing is reported to zipkin. However, this span should still be injected into outgoing requests. Use this flag to avoid performing expensive computation.

      • customizer

        public abstract SpanCustomizer customizer()
        Returns a customizer appropriate for the current span. Prefer this when invoking user code

      • start

        public abstract Span start()
        Starts the span with an implicit timestamp.

        Spans can be modified before calling start. For example, you can add tags to the span and set its name without lock contention.

      • start

        public abstract Span start​(long timestamp)
        Like start(), except with a given timestamp in microseconds.

        Take extreme care with this feature as it is easy to have incorrect timestamps. If you must use this, generate the timestamp using Tracing.clock(TraceContext).

      • name

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

      • kind

        public abstract Span kind​(@Nullable
                          Span.Kind kind)
        When present, the span is remote. This value clarifies how to interpret remoteServiceName(String) and remoteIpAndPort(String, int).

        Note: This affects Zipkin v1 format even if that format does not have a "kind" field. For example, if kind is Span.Kind.SERVER and reported in v1 Zipkin format, the span's start timestamp is implicitly annotated as "sr" and that plus its duration as "ss".

      • annotate

        public abstract Span 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"

      • annotate

        public abstract Span annotate​(long timestamp,
                              String value)
        Like annotate(String), except with a given timestamp in microseconds.

        Take extreme care with this feature as it is easy to have incorrect timestamps. If you must use this, generate the timestamp using Tracing.clock(TraceContext).

      • tag

        public abstract Span 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.
        See Also:
        Tag.tag(Object, SpanCustomizer)

      • error

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

        Note: Calling this does not finish the span.

        Since:
        4.19

      • remoteServiceName

        public abstract Span remoteServiceName​(String remoteServiceName)
        Lower-case label of the remote node in the service graph, such as "favstar". Do not set if unknown. Avoid names with variables or unique identifiers embedded.

        This is a primary label for trace lookup and aggregation, so it should be intuitive and consistent. Many use a name from service discovery.

        See Also:
        remoteIpAndPort(String, int)

      • remoteIpAndPort

        public abstract boolean remoteIpAndPort​(@Nullable
                                        String remoteIp,
                                        int remotePort)
        Sets the IP and port associated with the remote endpoint. For example, the server's listen socket or the connected client socket. This can also be set to forwarded values, such as an advertised IP.

        Invalid inputs, such as hostnames, will return false. Port is only set with a valid IP, and zero or negative port values are ignored. For example, to set only the IP address, leave port as zero.

        This returns boolean, not Span as it is often the case strings are malformed. Using this, you can do conditional parsing like so: 

        
 if (span.remoteIpAndPort(address.getHostAddress(), target.getPort())) return;
 span.remoteIpAndPort(address.getHostName(), target.getPort());

        Note: Comma separated lists are not supported. If you have multiple entries choose the one most indicative of the remote side. For example, the left-most entry in X-Forwarded-For.

        Parameters:
        remoteIp - the IPv4 or IPv6 literal representing the remote service connection
        remotePort - the port associated with the IP, or zero if unknown.
        Since:
        5.2
        See Also:
        remoteServiceName(String)

      • finish

        public abstract void finish()
        Reports the span complete, assigning the most precise duration possible.

      • abandon

        public abstract void abandon()
        Throws away the current span without reporting it.

      • finish

        public abstract void finish​(long timestamp)
        Like finish(), except with a given timestamp in microseconds.

        Zipkin's span duration is derived by subtracting the start timestamp from this, and set when appropriate.

        Take extreme care with this feature as it is easy to have incorrect timestamps. If you must use this, generate the timestamp using Tracing.clock(TraceContext).

      • flush

        public abstract void flush()
        Reports the span, even if unfinished. Most users will not call this method.

        This primarily supports two use cases: one-way spans and orphaned spans. For example, a one-way span can be modeled as a span where one tracer calls start and another calls finish. In order to report that span from its origin, flush must be called.

        Another example is where a user didn't call finish within a deadline or before a shutdown occurs. By flushing, you can report what was in progress.