public interface Span
An instance of a span. May represent either:
isNull() returns false
isNull() returns true (an instance of NullSpan).
When Plumbr Agent is not attached or the API version is too new for the agent, all methods returning a span
return a null span instead. When Plumbr Agent is attached and compatible with the API version, the only source
for null spans is the return value of Plumbr.getCurrentSpan() when there is no currently active span.
None of the methods of this interface throw an exception. Methods returning Span never return
null. Methods returning String may return null.
| Modifier and Type | Method and Description |
|---|---|
Span |
addMetadata(java.lang.String name,
java.lang.String value)
Add metadata with the specified name to the span.
|
Span |
createChildSpan()
Create the child span within the transaction of this span.
|
void |
fail(java.lang.Throwable t)
Mark current span as finished with failure and associate the throwable as the root cause.
|
void |
fail(java.lang.Throwable t,
boolean failEntireTransaction)
Mark current span as finished with failure and associate the throwable as the root cause.
|
void |
finish()
Mark the span as successfully finished.
|
void |
finishChildSpan(Span child)
Indicate that the child span is finished.
|
java.lang.String |
getAppName()
Deprecated.
Instead of application name, clusterId and jvmId properties are now used to determine under which API
in the UI the transaction will be listed. Always returns
null on latest agent. |
java.lang.String |
getMetadata(java.lang.String name)
Returns the value associated with the specified metadata field name.
|
java.lang.String |
getServiceName()
Get the service name of the current span.
|
java.lang.String |
getTransactionId() |
java.lang.String |
getUserId()
Get the user ID associated with the current span.
|
boolean |
isNull()
A null span is represented by an instance of a
Span where this method returns true. |
Span |
setAppName(java.lang.String appName)
Deprecated.
Instead of application name, clusterId and jvmId properties are now used to determine under which API
in the UI the transaction will be listed. Has no effect on latest agent.
|
Span |
setServiceName(java.lang.String serviceName)
Set the service name of the current span.
|
Span |
setUserId(java.lang.String userId)
Set the user ID for the current transaction.
|
void |
start()
Start the span and make it active.
|
boolean isNull()
Span where this method returns true. Methods
returning a Span never return null.false if this object refers to a valid span, true if it represents a null span.java.lang.String getTransactionId()
@Deprecated Span setAppName(java.lang.String appName)
appName - application name.@Deprecated java.lang.String getAppName()
null on latest agent.Span setServiceName(java.lang.String serviceName)
Set the service name of the current span. If a transaction consists of multiple spans, then any span may have its own service name. The service name of the transaction is the service name of the root span. For root spans started with the API, the service name must be set manually. In case the service name is not set for a root span, the whole transaction is discarded.
For root spans started automatically by the Plumbr Agent, a service name is always present, but may be overridden using this method.
serviceName - service name.java.lang.String getServiceName()
null
until the service name is set using setServiceName(String). For spans started automatically by the Plumbr
Agent, it returns the service ID automatically assigned by the agent, unless it is overridden by calling
setServiceName(String).Span setUserId(java.lang.String userId)
userId - user name.java.lang.String getUserId()
null until the user ID has been set using setUserId(String). For spans started automatically
by the Plumbr Agent, the user ID may have already been set automatically.Span addMetadata(java.lang.String name, java.lang.String value)
Add metadata with the specified name to the span. The metadata of each span can be seen from the single transaction view for an unhealthy transaction. A span supports up to 32 metadata fields, any new fields added after that limit is reached will be ignored. A new value for the same field name overrides the previous one.
Metadata is discarded in serialized format and must therefore be set on the same JVM where start() is
called.
name - Name of the metadata field.value - Value to store. Truncated to 1024 characters.java.lang.String getMetadata(java.lang.String name)
name - Name of the metadata field.null if not set.void start()
Start the span and make it active. The span must be made active for the root causes to be associated with the
span. One thread may have only one active span at a time. When this is called when another span started by the
API is already active, the previously active span will be ended as if finish() was called.
If the previously active span was not created via the API, then it will not be finished, but the root causes from the current thread will be associated with this span until it finished. The internally started span will be marked as finished at the time that it normally would, but root causes will not be attached to it while an API span is active.
Calling this method has no effect if the span has already been started. If a span is deserialized twice, then
calling start() on both of the deserialized instances may produce two separate spans.
Span createChildSpan()
start() on it.void finishChildSpan(Span child)
child - Child span to mark as finished.void finish()
Mark the span as successfully finished.
If it is the root span in the transaction or finishChildSpan(Span) has been called for all of its
children, then the transaction is finished as well. If there are child spans for which
finishChildSpan(Span) has not yet been called, the end of the last of those will determine the end time
of the transaction.
This method has no effect if the span has not been started, has already finished or was started in a different JVM.
void fail(java.lang.Throwable t)
fail(Throwable, boolean) with arguments fail(t, false).t - Throwable to associate as root cause. Pass null if there is no exception to blame.void fail(java.lang.Throwable t,
boolean failEntireTransaction)
t - Throwable to associate as root cause. Pass null if there is no exception to blame.failEntireTransaction - true means that the transaction which contains this span will be marked
as failed, regardless of how this span is handled by its parent.
false means that if in the chain from this span to the root span, any
span is ended with finishChildSpan(Span) by its parent, then the failure of
the current span has no direct effect on the status of the transaction.