Span (agent-api 19.12.18 API)

All Known Implementing Classes:

NullSpan
```
public interface Span
```
An instance of a span. May represent either:
- A valid span - isNull() returns false
- A null span - 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.

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
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.

- Method Detail
  - isNull
```
boolean isNull()
```
    A null span is represented by an instance of a Span where this method returns true. Methods returning a Span never return null.
    
    Returns:
    
    false if this object refers to a valid span, true if it represents a null span.
  - getTransactionId
```
java.lang.String getTransactionId()
```
    Returns:
    
    The ID of the current transaction. Never null (refer to NullSpan to see its return value for spans where isNull() returns true).
  - setAppName
```
@Deprecated
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.
    
    Parameters:
    
    appName - application name.
    
    Returns:
    
    current span to chain method calls.
  - getAppName
```
@Deprecated
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.
    
    Returns:
    
    application name.
  - setServiceName
```
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.
    
    Parameters:
    
    serviceName - service name.
    
    Returns:
    
    This span to chain method calls.
  - getServiceName
```
java.lang.String getServiceName()
```
    Get the service name of the current span. In case of a span started with the API, it returns 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).
    
    Returns:
    
    Service name of the this span.
  - setUserId
```
Span setUserId(java.lang.String userId)
```
    Set the user ID for the current transaction.
    
    Parameters:
    
    userId - user name.
    
    Returns:
    
    current span to chain method calls.
  - getUserId
```
java.lang.String getUserId()
```
    Get the user ID associated with the current span. In case of a span started with the API, it returns 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.
    
    Returns:
    
    User ID associated with this span.
  - addMetadata
```
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.
    
    Parameters:
    
    name - Name of the metadata field.
    
    value - Value to store. Truncated to 1024 characters.
    
    Returns:
    
    current span to chain method calls.
  - getMetadata
```
java.lang.String getMetadata(java.lang.String name)
```
    Returns the value associated with the specified metadata field name. Some metadata fields may be automatically set for spans created internally by the Plumbr Agent, for example Url and HTTP Method.
    
    Parameters:
    
    name - Name of the metadata field.
    
    Returns:
    
    Current value of the specified metadata field. null if not set.
  - start
```
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.
  - createChildSpan
```
Span createChildSpan()
```
    Create the child span within the transaction of this span.
    
    Returns:
    
    the new created child span, which must be transferred to another thread or another JVM before invoking start() on it.
  - finishChildSpan
```
void finishChildSpan(Span child)
```
    Indicate that the child span is finished. If the child span is marked as finished by the parent span, then the parent decides the status of its subtree of spans in the span tree of the transaction. If the child span is not marked as finished by the parent span, then if the child span fails, it will mark the transaction as failed.
    
    Parameters:
    
    child - Child span to mark as finished.
  - finish
```
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.
  - fail
```
void fail(java.lang.Throwable t)
```
    Mark current span as finished with failure and associate the throwable as the root cause. This is equivalent to calling fail(Throwable, boolean) with arguments fail(t, false).
    
    Parameters:
    
    t - Throwable to associate as root cause. Pass null if there is no exception to blame.
  - fail
```
void fail(java.lang.Throwable t,
          boolean failEntireTransaction)
```
    Mark current span as finished with failure and associate the throwable as the root cause.
    
    Parameters:
    
    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.

Interface Span

Method Summary

Method Detail

isNull

getTransactionId

setAppName

getAppName

setServiceName

getServiceName

setUserId

getUserId

addMetadata

getMetadata

start

createChildSpan

finishChildSpan

finish

fail

fail