Class MutableSpan
- All Implemented Interfaces:
Cloneable
public final class MutableSpan extends Object implements Cloneable
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.
- 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
Modifier and Type Method Description void
annotate(long timestamp, String value)
Calling this adds an annotation, such as done inSpanCustomizer.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 givenindex
or throwsIndexOutOfBoundsException
if the index is invalid.String
annotationValueAt(int i)
Returns the possibly empty value of the annotation at the givenindex
or throwsIndexOutOfBoundsException
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 ornull
.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 asSpan.finish(long)
orScopedSpan.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 useequals(Object)
against a base value.Span.Kind
kind()
Returns the span kind ornull
.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 ornull
.boolean
localIp(String localIp)
Calling this overrides any previous value, such asTracing.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 asTracing.Builder.localPort(int)
.String
localRootId()
Returns the local root IDvoid
localRootId(String localRootId)
Calling this overrides the local root ID.String
localServiceName()
Returns the label of this node in the service graph ornull
.void
localServiceName(String localServiceName)
Calling this overrides any previous value, such asTracing.Builder.localServiceName(String)
.String
name()
Returns the span name ornull
void
name(String name)
Calling this overrides any previous value, such asSpanCustomizer.name(String)
.String
parentId()
Returns the parent ID ornull
void
parentId(String parentId)
Calling this overrides the parent ID.String
remoteIp()
Returns the IP of the remote service ornull
.void
remoteIp(String remoteIp)
Calling this overrides any previous value, such as fromSpan.remoteIpAndPort(String, int)
.boolean
remoteIpAndPort(String remoteIp, int remotePort)
WhenremoteIp
is notnull
, calling this overrides any previous value, such asSpan.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 fromSpan.remoteIpAndPort(String, int)
.String
remoteServiceName()
Returns the primary label of the remote service ornull
.void
remoteServiceName(String remoteServiceName)
Calling this overrides any previous value, such asSpan.remoteServiceName(String)
.String
removeTag(String key)
Removes and returns the last tag value associated with the key or returnsnull
if it was never set.void
setDebug()
Calling this is unexpected as it should only be initialized bySamplingFlags.debug()
.void
setShared()
Calling this is unexpected as it should only be initialized byTraceContext.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 asSpan.start(long)
orTracer.startScopedSpan(String)
.String
tag(String key)
Returns the last tag value associated with the key ornull
.void
tag(String key, String value)
Calling this overrides any previous value, such asSpanCustomizer.tag(String, String)
.int
tagCount()
String
tagKeyAt(int i)
Returns the tag key at the givenindex
or throwsIndexOutOfBoundsException
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 givenindex
or throwsIndexOutOfBoundsException
if the index is invalid.String
toString()
String
traceId()
Returns the trace IDvoid
traceId(String traceId)
Calling this overrides the trace ID.void
unsetDebug()
void
unsetShared()
-
Constructor Details
-
MutableSpan
public MutableSpan()- Since:
- 5.4
-
MutableSpan
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
- Since:
- 5.12
-
-
Method Details
-
isEmpty
Deprecated.Since 5.12 useequals(Object)
against a base value.- Since:
- 5.4
-
traceId
Returns the trace ID- Since:
- 5.12
-
traceId
Calling this overrides the trace ID.- See Also:
traceId()
-
localRootId
Returns the local root ID- Since:
- 5.12
-
localRootId
Calling this overrides the local root ID.- See Also:
localRootId()
-
parentId
Returns the parent ID ornull
- Since:
- 5.12
-
parentId
Calling this overrides the parent ID.- See Also:
parentId()
-
id
Returns the span ID.- Since:
- 5.12
-
id
Calling this overrides the span ID.- See Also:
id()
-
name
Returns the span name ornull
- Since:
- 5.4
-
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 asSpan.start(long)
orTracer.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 asSpan.finish(long)
orScopedSpan.finish()
.- See Also:
finishTimestamp()
-
kind
Returns the span kind ornull
.- Since:
- 5.4
-
kind
Calling this overrides any previous value, such as {@link brave.Span#kind(Kind).- See Also:
kind()
-
localServiceName
Returns the label of this node in the service graph ornull
.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
Calling this overrides any previous value, such asTracing.Builder.localServiceName(String)
.- See Also:
localServiceName()
-
localIp
Returns the primary IP address associated with this service ornull
.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
Calling this overrides any previous value, such asTracing.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 asTracing.Builder.localPort(int)
.- See Also:
localPort()
-
remoteServiceName
Returns the primary label of the remote service ornull
.- Since:
- 5.4
- See Also:
remoteIp()
,remotePort()
-
remoteServiceName
Calling this overrides any previous value, such asSpan.remoteServiceName(String)
.- See Also:
remoteServiceName()
-
remoteIp
Returns the IP of the remote service ornull
.- Since:
- 5.4
- See Also:
remoteServiceName()
,remotePort()
-
remoteIp
Calling this overrides any previous value, such as fromSpan.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 fromSpan.remoteIpAndPort(String, int)
.- See Also:
remoteIpAndPort(String, int)
-
remoteIpAndPort
WhenremoteIp
is notnull
, calling this overrides any previous value, such asSpan.remoteIpAndPort(String, int)
.- See Also:
remoteServiceName()
,remoteIp()
,remotePort()
-
error
Returns the error ornull
.- Since:
- 5.4
-
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 bySamplingFlags.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 byTraceContext.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 givenindex
or throwsIndexOutOfBoundsException
if the index is invalid. -
annotationValueAt
Returns the possibly empty value of the annotation at the givenindex
or throwsIndexOutOfBoundsException
if the index is invalid. -
annotations
A read-only view of the current annotations as a collection of(epochMicroseconds -> value)
.- Since:
- 5.12
- See Also:
forEachAnnotation(AnnotationConsumer, Object)
-
forEachAnnotation
Iterates over all annotations for purposes such as copying values. Unlikeannotations()
, 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
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
Returns true if an annotation with the given value exists in this span.- Since:
- 5.4
- See Also:
forEachAnnotation(AnnotationConsumer, Object)
,forEachAnnotation(AnnotationUpdater)
-
annotate
Calling this adds an annotation, such as done inSpanCustomizer.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
Returns the tag key at the givenindex
or throwsIndexOutOfBoundsException
if the index is invalid. -
tagValueAt
Returns the possibly empty value at the givenindex
or throwsIndexOutOfBoundsException
if the index is invalid. -
tags
A read-only view of the current tags a map.- Since:
- 5.12
- See Also:
forEachTag(TagConsumer, Object)
-
tag
Returns the last tag value associated with the key ornull
.- Since:
- 5.4
-
removeTag
Removes and returns the last tag value associated with the key or returnsnull
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
Iterates over all tags for purposes such as copying values. Unliketags()
, 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
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
Calling this overrides any previous value, such asSpanCustomizer.tag(String, String)
.- See Also:
tag(String)
-
toString
-
hashCode
public int hashCode() -
equals
-