java.lang.Object
- brave.handler.MutableSpan

All Implemented Interfaces:

Cloneable
```
public final class MutableSpan
extends Object
implements Cloneable
```
This represents a span except for its TraceContext. It is mutable, for late adjustments.
Notes

Between SpanHandler.begin(TraceContext, MutableSpan, TraceContext) and SpanHandler.end(TraceContext, MutableSpan, SpanHandler.Cause), Brave owns this reference, synchronizing where necessary as updates come from different application threads.
Upon end, Brave no longer makes updates. It invokes each SpanHandler, one-by-one on the same thread. This means subsequent handlers do not have to synchronize to view updates from a prior one. However, it does imply they must make mutations on the same thread.
In other words, this type is not thread safe. If you need to mutate this span in a different thread, use the copy constructor.
MutableSpan.error() vs MutableSpan.tag("error")
If tag(String) returns a result for "error", it was from a layered api, instrumentation or the user. error() is usually an uncaught exception and does not imply there's a tag "error".
Here are examples of a span with error(), but no "error" tag:
- brave.Span.error(new OutOfMemoryError()) -> MutableSpan.error(new OutOfMemoryError())
- brave.Span.error(new RpcException()) -> MutableSpan.error(new RpcException())
- brave.Span.error(new NullPointerException()) -> MutableSpan.error(new NullPointerException())
The above are examples of exceptions that users typically do not process, so are unlikely to parse into an "error" tag. The opposite is also true as not all errors are derived from Throwable. Particularly, RPC frameworks often do not use exceptions as error signals.
Here are examples of a span with an "error" tag, but no error():
- io.opentracing.Span.tag(ERROR, true) -> MutableSpan.tag("error", "true")
- brave.SpanCustomizer.tag("error", "") -> MutableSpan.tag("error", "")
- brave.Span.tag("error", "CANCELLED") -> MutableSpan.tag("error", "CANCELLED")
The above examples are using in-band apis in Brave. SpanHandler is after the fact. Since there is no default "error" tag, span handlers here can tell the difference between explicitly set error messages, and what's needed by their format. For example, those only looking at Zipkin clones may forget that error() exists for custom formats including metrics!
Here are examples of SpanHandler.end(TraceContext, MutableSpan, SpanHandler.Cause) implementations that process errors:
- MutableSpan.tag("error", "") to redact the error message from Zipkin
- MutableSpan.error() -> MutableSpan.tag("exception", normalized) to match metrics dimension
- MutableSpan.error() -> CustomFormat.stackTrace for sophisticated trace formats
In summary, Brave intentionally does not default an "error" tag(String) from error(). This allows SpanHandler instances that report data be as simple as an error bit, or advanced enough to keep a stacktrace and also a user tag.
Since:

5.4

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static interface`	`MutableSpan.AnnotationConsumer<T>`
`static interface`	`MutableSpan.AnnotationUpdater`
`static interface`	`MutableSpan.TagConsumer<T>`
`static interface`	`MutableSpan.TagUpdater`

Constructor Summary

Constructors
Constructor	Description
`MutableSpan()`
`MutableSpan(MutableSpan toCopy)`
`MutableSpan(TraceContext context, MutableSpan defaults)`	Creates a new instance from the given context, and defaults in the span.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`void`	`annotate(long timestamp, String value)`	Calling this adds an annotation, such as done in `SpanCustomizer.annotate(String)`.
`int`	`annotationCount()`
`Collection<Map.Entry<Long,String>>`	`annotations()`	A read-only view of the current annotations as a collection of `(epochMicroseconds -> value)`.
`long`	`annotationTimestampAt(int i)`	Returns the epoch microseconds of the annotation at the given `index` or throws `IndexOutOfBoundsException` if the index is invalid.
`String`	`annotationValueAt(int i)`	Returns the possibly empty value of the annotation at the given `index` or throws `IndexOutOfBoundsException` if the index is invalid.
`boolean`	`containsAnnotation(String value)`	Returns true if an annotation with the given value exists in this span.
`boolean`	`debug()`	Returns true if the context was debug.
`boolean`	`equals(Object o)`
`Throwable`	`error()`	Returns the error or `null`.
`void`	`error(Throwable error)`	Calling this overrides any previous value, such as {@link brave.Span#error(Throwable).
`long`	`finishTimestamp()`	Returns the span finish timestamp or zero.
`void`	`finishTimestamp(long finishTimestamp)`	Calling this overrides any previous value, such as `Span.finish(long)` or `ScopedSpan.finish()`.
`<T> void`	`forEachAnnotation(MutableSpan.AnnotationConsumer<T> annotationConsumer, T target)`	Iterates over all annotations for purposes such as copying values.
`void`	`forEachAnnotation(MutableSpan.AnnotationUpdater annotationUpdater)`	Allows you to update or drop annotations for purposes such as redaction.
`<T> void`	`forEachTag(MutableSpan.TagConsumer<T> tagConsumer, T target)`	Iterates over all tags for purposes such as copying values.
`void`	`forEachTag(MutableSpan.TagUpdater tagUpdater)`	Allows you to update or drop tags for purposes such as redaction.
`int`	`hashCode()`
`String`	`id()`	Returns the span ID.
`void`	`id(String id)`	Calling this overrides the span ID.
`boolean`	`isEmpty()`	Deprecated. Since 5.12 use `equals(Object)` against a base value.
`Span.Kind`	`kind()`	Returns the span kind or `null`.
`void`	`kind(Span.Kind kind)`	Calling this overrides any previous value, such as {@link brave.Span#kind(Kind).
`String`	`localIp()`	Returns the primary IP address associated with this service or `null`.
`boolean`	`localIp(String localIp)`	Calling this overrides any previous value, such as `Tracing.Builder.localIp(String)`.
`int`	`localPort()`	Returns the primary listen port associated with this service or zero.
`void`	`localPort(int localPort)`	Calling this overrides any previous value, such as `Tracing.Builder.localPort(int)`.
`String`	`localRootId()`	Returns the local root ID
`void`	`localRootId(String localRootId)`	Calling this overrides the local root ID.
`String`	`localServiceName()`	Returns the label of this node in the service graph or `null`.
`void`	`localServiceName(String localServiceName)`	Calling this overrides any previous value, such as `Tracing.Builder.localServiceName(String)`.
`String`	`name()`	Returns the span name or `null`
`void`	`name(String name)`	Calling this overrides any previous value, such as`SpanCustomizer.name(String)`.
`String`	`parentId()`	Returns the parent ID or `null`
`void`	`parentId(String parentId)`	Calling this overrides the parent ID.
`String`	`remoteIp()`	Returns the IP of the remote service or `null`.
`void`	`remoteIp(String remoteIp)`	Calling this overrides any previous value, such as from `Span.remoteIpAndPort(String, int)`.
`boolean`	`remoteIpAndPort(String remoteIp, int remotePort)`	When `remoteIp` is not `null`, calling this overrides any previous value, such as `Span.remoteIpAndPort(String, int)`.
`int`	`remotePort()`	Returns the port of the remote service or zero.
`void`	`remotePort(int remotePort)`	Calling this overrides any previous value, such as from `Span.remoteIpAndPort(String, int)`.
`String`	`remoteServiceName()`	Returns the primary label of the remote service or `null`.
`void`	`remoteServiceName(String remoteServiceName)`	Calling this overrides any previous value, such as `Span.remoteServiceName(String)`.
`String`	`removeTag(String key)`	Removes and returns the last tag value associated with the key or returns `null` if it was never set.
`void`	`setDebug()`	Calling this is unexpected as it should only be initialized by `SamplingFlags.debug()`.
`void`	`setShared()`	Calling this is unexpected as it should only be initialized by `TraceContext.shared()`.
`boolean`	`shared()`	Returns true if the context was shared.
`long`	`startTimestamp()`	Returns the span start timestamp or zero.
`void`	`startTimestamp(long startTimestamp)`	Calling this overrides any previous value, such as `Span.start(long)` or `Tracer.startScopedSpan(String)`.
`String`	`tag(String key)`	Returns the last tag value associated with the key or `null`.
`void`	`tag(String key, String value)`	Calling this overrides any previous value, such as `SpanCustomizer.tag(String, String)`.
`int`	`tagCount()`
`String`	`tagKeyAt(int i)`	Returns the tag key at the given `index` or throws `IndexOutOfBoundsException` if the index is invalid.
`Map<String,String>`	`tags()`	A read-only view of the current tags a map.
`String`	`tagValueAt(int i)`	Returns the possibly empty value at the given `index` or throws `IndexOutOfBoundsException` if the index is invalid.
`String`	`toString()`
`String`	`traceId()`	Returns the trace ID
`void`	`traceId(String traceId)`	Calling this overrides the trace ID.
`void`	`unsetDebug()`
`void`	`unsetShared()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - MutableSpan
```
public MutableSpan()
```
    Since:
    
    5.4
  - MutableSpan
```
public MutableSpan(TraceContext context,
                   @Nullable
                   MutableSpan defaults)
```
    Creates a new instance from the given context, and defaults in the span.
    Note: It is unexpected to have context properties also in the span defaults. The context will win in this case, as opposed to throwing an exception.
    
    Since:
    
    5.12
  - MutableSpan
```
public MutableSpan(MutableSpan toCopy)
```
    Since:
    
    5.12
- Method Detail
  - isEmpty
```
@Deprecated
public boolean isEmpty()
```
    Deprecated.
    Since 5.12 use equals(Object) against a base value.
    
    Since:
    
    5.4
  - traceId
```
public String traceId()
```
    Returns the trace ID
    
    Since:
    
    5.12
  - traceId
```
public void traceId(String traceId)
```
    Calling this overrides the trace ID.
    
    See Also:
    
    traceId()
  - localRootId
```
@Nullable
public String localRootId()
```
    Returns the local root ID
    
    Since:
    
    5.12
  - localRootId
```
public void localRootId(String localRootId)
```
    Calling this overrides the local root ID.
    
    See Also:
    
    localRootId()
  - parentId
```
@Nullable
public String parentId()
```
    Returns the parent ID or null
    
    Since:
    
    5.12
  - parentId
```
public void parentId(@Nullable
                     String parentId)
```
    Calling this overrides the parent ID.
    
    See Also:
    
    parentId()
  - id
```
public String id()
```
    Returns the span ID.
    
    Since:
    
    5.12
  - id
```
public void id(String id)
```
    Calling this overrides the span ID.
    
    See Also:
    
    id()
  - name
```
@Nullable
public String name()
```
    Returns the span name or null
    
    Since:
    
    5.4
  - name
```
public void name(@Nullable
                 String name)
```
    Calling this overrides any previous value, such asSpanCustomizer.name(String).
    
    See Also:
    
    name()
  - startTimestamp
```
public long startTimestamp()
```
    Returns the span start timestamp or zero.
    
    Since:
    
    5.4
  - startTimestamp
```
public void startTimestamp(long startTimestamp)
```
    Calling this overrides any previous value, such as Span.start(long) or Tracer.startScopedSpan(String).
    
    See Also:
    
    startTimestamp()
  - finishTimestamp
```
public long finishTimestamp()
```
    Returns the span finish timestamp or zero.
    
    Since:
    
    5.4
  - finishTimestamp
```
public void finishTimestamp(long finishTimestamp)
```
    Calling this overrides any previous value, such as Span.finish(long) or ScopedSpan.finish().
    
    See Also:
    
    finishTimestamp()
  - kind
```
public Span.Kind kind()
```
    Returns the span kind or null.
    
    Since:
    
    5.4
  - kind
```
public void kind(@Nullable
                 Span.Kind kind)
```
    Calling this overrides any previous value, such as {@link brave.Span#kind(Kind).
    
    See Also:
    
    kind()
  - localServiceName
```
@Nullable
public String localServiceName()
```
    Returns the label of this node in the service graph or null.
    Note: This is initialized from Tracing.Builder.localServiceName(String). handlers that want to conditionally replace the value should compare against the same value given to the tracing component.
    
    Since:
    
    5.4
  - localServiceName
```
public void localServiceName(@Nullable
                             String localServiceName)
```
    Calling this overrides any previous value, such as Tracing.Builder.localServiceName(String).
    
    See Also:
    
    localServiceName()
  - localIp
```
@Nullable
public String localIp()
```
    Returns the primary IP address associated with this service or null.
    Note: This is initialized from Tracing.Builder.localIp(String). handlers that want to conditionally replace the value should compare against the same value given to the tracing component.
    
    Since:
    
    5.4
  - localIp
```
public boolean localIp(@Nullable
                       String localIp)
```
    Calling this overrides any previous value, such as Tracing.Builder.localIp(String).
    
    See Also:
    
    localIp()
  - localPort
```
public int localPort()
```
    Returns the primary listen port associated with this service or zero.
    Note: This is initialized from Tracing.Builder.localPort(int). handlers that want to conditionally replace the value should compare against the same value given to the tracing component.
    
    Since:
    
    5.4
  - localPort
```
public void localPort(int localPort)
```
    Calling this overrides any previous value, such as Tracing.Builder.localPort(int).
    
    See Also:
    
    localPort()
  - remoteServiceName
```
@Nullable
public String remoteServiceName()
```
    Returns the primary label of the remote service or null.
    
    Since:
    
    5.4
    
    See Also:
    
    remoteIp(), remotePort()
  - remoteServiceName
```
public void remoteServiceName(@Nullable
                              String remoteServiceName)
```
    Calling this overrides any previous value, such as Span.remoteServiceName(String).
    
    See Also:
    
    remoteServiceName()
  - remoteIp
```
@Nullable
public String remoteIp()
```
    Returns the IP of the remote service or null.
    
    Since:
    
    5.4
    
    See Also:
    
    remoteServiceName(), remotePort()
  - remoteIp
```
public void remoteIp(@Nullable
                     String remoteIp)
```
    Calling this overrides any previous value, such as from Span.remoteIpAndPort(String, int).
    
    See Also:
    
    remoteIpAndPort(String, int)
  - remotePort
```
public int remotePort()
```
    Returns the port of the remote service or zero.
    
    Since:
    
    5.4
    
    See Also:
    
    remoteServiceName(), remoteIp()
  - remotePort
```
public void remotePort(int remotePort)
```
    Calling this overrides any previous value, such as from Span.remoteIpAndPort(String, int).
    
    See Also:
    
    remoteIpAndPort(String, int)
  - remoteIpAndPort
```
public boolean remoteIpAndPort(@Nullable
                               String remoteIp,
                               int remotePort)
```
    When remoteIp is not null, calling this overrides any previous value, such as Span.remoteIpAndPort(String, int).
    
    See Also:
    
    remoteServiceName(), remoteIp(), remotePort()
  - error
```
public Throwable error()
```
    Returns the error or null.
    
    Since:
    
    5.4
  - error
```
public void error(@Nullable
                  Throwable error)
```
    Calling this overrides any previous value, such as {@link brave.Span#error(Throwable).
    
    See Also:
    
    error()
  - debug
```
public boolean debug()
```
    Returns true if the context was debug.
    
    Since:
    
    5.4
  - setDebug
```
public void setDebug()
```
    Calling this is unexpected as it should only be initialized by SamplingFlags.debug().
    
    Since:
    
    5.4
    
    See Also:
    
    debug(), unsetDebug()
  - unsetDebug
```
public void unsetDebug()
```
    Since:
    
    5.12
    
    See Also:
    
    setDebug()
  - shared
```
public boolean shared()
```
    Returns true if the context was shared.
    
    Since:
    
    5.4
  - setShared
```
public void setShared()
```
    Calling this is unexpected as it should only be initialized by TraceContext.shared().
    
    Since:
    
    5.4
    
    See Also:
    
    shared(), unsetShared()
  - unsetShared
```
public void unsetShared()
```
    Since:
    
    5.12
    
    See Also:
    
    setShared()
  - annotationCount
```
public int annotationCount()
```
    Since:
    
    5.12
    
    See Also:
    
    annotationTimestampAt(int), annotationValueAt(int)
  - annotationTimestampAt
```
public long annotationTimestampAt(int i)
```
    Returns the epoch microseconds of the annotation at the given index or throws IndexOutOfBoundsException if the index is invalid.
    
    See Also:
    
    annotationCount(), annotationValueAt(int), Span.annotate(long, String)
  - annotationValueAt
```
public String annotationValueAt(int i)
```
    Returns the possibly empty value of the annotation at the given index or throws IndexOutOfBoundsException if the index is invalid.
    
    See Also:
    
    annotationCount(), annotationTimestampAt(int), Span.annotate(long, String)
  - annotations
```
public Collection<Map.Entry<Long,String>> annotations()
```
    A read-only view of the current annotations as a collection of (epochMicroseconds -> value).
    
    Since:
    
    5.12
    
    See Also:
    
    forEachAnnotation(AnnotationConsumer, Object)
  - forEachAnnotation
```
public <T> void forEachAnnotation(MutableSpan.AnnotationConsumer<T> annotationConsumer,
                                  T target)
```
    Iterates over all annotations for purposes such as copying values. Unlike annotations(), using this is allocation free.
    Ex.
    // During initialization, cache an annotation consumer function: annotationConsumer = (target, timestamp, value) -> target.add(tuple(timestamp, value)); // Re-use that function while processing spans. List<Tuple<Long, String>> list = new ArrayList<>(); span.forEachAnnotation(annotationConsumer, list);
    Since:
    
    5.4
    
    See Also:
    
    forEachAnnotation(AnnotationUpdater), annotations()
  - forEachAnnotation
```
public void forEachAnnotation(MutableSpan.AnnotationUpdater annotationUpdater)
```
    Allows you to update or drop annotations for purposes such as redaction.
    Ex.
    // During initialization, cache an annotation updater function: annotationRedacter = (timestamp, value) -> badWords.contains(value) ? null : value; // Re-use that function while processing spans. span.forEachAnnotation(annotationRedacter);
    Since:
    
    5.4
    
    See Also:
    
    forEachAnnotation(AnnotationConsumer, Object)
  - containsAnnotation
```
public boolean containsAnnotation(String value)
```
    Returns true if an annotation with the given value exists in this span.
    
    Since:
    
    5.4
    
    See Also:
    
    forEachAnnotation(AnnotationConsumer, Object), forEachAnnotation(AnnotationUpdater)
  - annotate
```
public void annotate(long timestamp,
                     String value)
```
    Calling this adds an annotation, such as done in SpanCustomizer.annotate(String).
    
    Since:
    
    5.4
    
    See Also:
    
    forEachAnnotation(AnnotationConsumer, Object), forEachAnnotation(AnnotationUpdater)
  - tagCount
```
public int tagCount()
```
    Since:
    
    5.12
    
    See Also:
    
    tagKeyAt(int), tagValueAt(int)
  - tagKeyAt
```
public String tagKeyAt(int i)
```
    Returns the tag key at the given index or throws IndexOutOfBoundsException if the index is invalid.
    
    See Also:
    
    tagCount(), tagValueAt(int), SpanCustomizer.tag(String, String)
  - tagValueAt
```
public String tagValueAt(int i)
```
    Returns the possibly empty value at the given index or throws IndexOutOfBoundsException if the index is invalid.
    
    See Also:
    
    tagCount(), tagKeyAt(int), SpanCustomizer.tag(String, String)
  - tags
```
public Map<String,String> tags()
```
    A read-only view of the current tags a map.
    
    Since:
    
    5.12
    
    See Also:
    
    forEachTag(TagConsumer, Object)
  - tag
```
@Nullable
public String tag(String key)
```
    Returns the last tag value associated with the key or null.
    
    Since:
    
    5.4
  - removeTag
```
@Nullable
public String removeTag(String key)
```
    Removes and returns the last tag value associated with the key or returns null if it was never set.
    Ex. to remove any tag named "remoteServiceName" and set it as remoteServiceName(String) instead:
    String remoteServiceName = span.removeTag("peer.service"); if (remoteServiceName != null) span.remoteServiceName(remoteServiceName);
    Since:
    
    5.12
  - forEachTag
```
public <T> void forEachTag(MutableSpan.TagConsumer<T> tagConsumer,
                           T target)
```
    Iterates over all tags for purposes such as copying values. Unlike tags(), using this is allocation free.
    Ex.
    Map<String, String> tags = new LinkedHashMap<>(); span.forEachTag(Map::put, tags);
    Since:
    
    5.4
    
    See Also:
    
    forEachTag(TagUpdater), tag(String), tags()
  - forEachTag
```
public void forEachTag(MutableSpan.TagUpdater tagUpdater)
```
    Allows you to update or drop tags for purposes such as redaction.
    Ex.
    // During initialization, cache an tag updater function: tagRedacter = (key, value) -> badWords.contains(value) ? null : value; // Re-use that function while processing spans. span.forEachTag(tagRedacter);
    Since:
    
    5.4
    
    See Also:
    
    forEachTag(TagConsumer, Object), tag(String)
  - tag
```
public void tag(String key,
                String value)
```
    Calling this overrides any previous value, such as SpanCustomizer.tag(String, String).
    
    See Also:
    
    tag(String)
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object

Class MutableSpan

Notes

MutableSpan.error() vs MutableSpan.tag("error")

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MutableSpan

MutableSpan

MutableSpan

Method Detail

isEmpty

traceId

traceId

localRootId

localRootId

parentId

parentId

id

id

name

name

startTimestamp

startTimestamp

finishTimestamp

finishTimestamp

kind

kind

localServiceName

localServiceName

localIp

localIp

localPort

localPort

remoteServiceName

remoteServiceName

remoteIp

remoteIp

remotePort

remotePort

remoteIpAndPort

error

error

debug

setDebug

unsetDebug

shared

setShared

unsetShared

annotationCount

annotationTimestampAt

annotationValueAt

annotations

forEachAnnotation

forEachAnnotation

containsAnnotation

annotate

tagCount

tagKeyAt

tagValueAt

tags

tag

removeTag

forEachTag

forEachTag

tag

toString

hashCode

equals