Package brave

Class Span

java.lang.Object
brave.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 Details

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

    • context

      public abstract TraceContext context()

    • 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

    • remoteEndpoint

      @Deprecated public Span remoteEndpoint​(zipkin2.Endpoint endpoint)
      Deprecated.
      Since 5.0, use remoteServiceName(String) remoteIpAndPort(String, int).

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