Span (Brave 5.2.0 API)

java.lang.Object
- brave.Span

All Implemented Interfaces:: SpanCustomizer

public abstract class Span
extends Object
implements SpanCustomizer

Used to model the latency 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.

Note: 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.

Nested Class Summary

Nested Classes
Modifier and Type Class Description

static class Span.Kind

Nested Classes
Modifier and Type	Class	Description
`static class`	`Span.Kind`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`abstract void`	`abandon()`	Throws away the current span without reporting it.
`abstract Span`	`annotate(long timestamp, String value)`	Like `annotate(String)`, except with a given timestamp in microseconds.
`abstract Span`	`annotate(String value)`	Associates an event that explains latency with the current system time.
`abstract TraceContext`	`context()`
`abstract SpanCustomizer`	`customizer()`	Returns a customizer appropriate for the current span.
`abstract Span`	`error(Throwable throwable)`	Adds tags depending on the configured `error parser`
`abstract void`	`finish()`	Reports the span complete, assigning the most precise duration possible.
`abstract void`	`finish(long timestamp)`	Like `finish()`, except with a given timestamp in microseconds.
`abstract void`	`flush()`	Reports the span, even if unfinished.
`abstract boolean`	`isNoop()`	When true, no recording is done and nothing is reported to zipkin.
`abstract Span`	`kind(Span.Kind kind)`	The kind of span is optional.
`abstract Span`	`name(String name)`	Sets the string name for the logical operation this span represents.
`Span`	`remoteEndpoint(zipkin2.Endpoint endpoint)`	Deprecated. Use `remoteServiceName(String)` `remoteIpAndPort(String, int)`. Will be removed in Brave v6.
`abstract boolean`	`remoteIpAndPort(String remoteIp, int remotePort)`	Sets the IP and port associated with the remote endpoint.
`abstract Span`	`remoteServiceName(String remoteServiceName)`	Lower-case label of the remote node in the service graph, such as "favstar".
`abstract Span`	`start()`	Starts the span with an implicit timestamp.
`abstract Span`	`start(long timestamp)`	Like `start()`, except with a given timestamp in microseconds.
`abstract Span`	`tag(String key, 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 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(Span.Kind kind)
```
    The kind of span is optional. When set, it affects how a span is reported. For example, if the kind is Span.Kind.SERVER, 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.
    
    Specified by:
    
    tag in interface SpanCustomizer
    
    Parameters:
    
    key - Name used to lookup spans, such as "your_app.version".
    
    value - String value, cannot be null.
  - error
```
public abstract Span error(Throwable throwable)
```
    Adds tags depending on the configured error parser
  - remoteEndpoint
```
@Deprecated
public Span remoteEndpoint(zipkin2.Endpoint endpoint)
```
    Deprecated. Use remoteServiceName(String) remoteIpAndPort(String, int). Will be removed in Brave v6.
  - 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.

Class Span

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

isNoop

context

customizer

start

start

name

kind

annotate

annotate

tag

error

remoteEndpoint

remoteServiceName

remoteIpAndPort

finish

abandon

finish

flush