eu.plumbr.api.noop

Class NullSpan

java.lang.Object

eu.plumbr.api.noop.NullSpan

All Implemented Interfaces:

Span

public class NullSpan
extends java.lang.Object
implements Span

Represents a null span. Since none of the methods returning a Span return null, they instead return an instance of Span where Span.isNull() returns true and which is an instance of this class.

Constructor Summary

Constructors

Constructor and Description
NullSpan()

Method Summary

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()
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)
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NullSpan

public NullSpan()

Method Detail

isNull

public boolean isNull()

Description copied from interface: Span

A null span is represented by an instance of a Span where this method returns true. Methods returning a Span never return null.

Specified by:

isNull in interface Span

Returns:

false if this object refers to a valid span, true if it represents a null span.

getTransactionId

public java.lang.String getTransactionId()

Specified by:

getTransactionId in interface Span

Returns:

The ID of the current transaction. Never null (refer to NullSpan to see its return value for spans where Span.isNull() returns true).

setAppName

public Span setAppName(java.lang.String appName)

Specified by:

setAppName in interface Span

Parameters:

appName - application name.

Returns:

current span to chain method calls.

getAppName

public java.lang.String getAppName()

Specified by:

getAppName in interface Span

Returns:

application name.

setServiceName

public Span setServiceName(java.lang.String serviceName)

Description copied from interface: Span

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.

Specified by:

setServiceName in interface Span

Parameters:

serviceName - service name.

Returns:

This span to chain method calls.

getServiceName

public java.lang.String getServiceName()

Description copied from interface: Span

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 Span.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 Span.setServiceName(String).

Specified by:

getServiceName in interface Span

Returns:

Service name of the this span.

setUserId

public Span setUserId(java.lang.String userId)

Description copied from interface: Span

Set the user ID for the current transaction.

Specified by:

setUserId in interface Span

Parameters:

userId - user name.

Returns:

current span to chain method calls.

getUserId

public java.lang.String getUserId()

Description copied from interface: Span

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 Span.setUserId(String). For spans started automatically by the Plumbr Agent, the user ID may have already been set automatically.

Specified by:

getUserId in interface Span

Returns:

User ID associated with this span.

addMetadata

public Span addMetadata(java.lang.String name,
                        java.lang.String value)

Description copied from interface: Span

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 Span.start() is called.

Specified by:

addMetadata in interface Span

Parameters:

name - Name of the metadata field.

value - Value to store. Truncated to 1024 characters.

Returns:

current span to chain method calls.

getMetadata

public java.lang.String getMetadata(java.lang.String name)

Description copied from interface: Span

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.

Specified by:

getMetadata in interface Span

Parameters:

name - Name of the metadata field.

Returns:

Current value of the specified metadata field. null if not set.

start

public void start()

Description copied from interface: Span

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 Span.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 Span.start() on both of the deserialized instances may produce two separate spans.

Specified by:

start in interface Span

createChildSpan

public Span createChildSpan()

Description copied from interface: Span

Create the child span within the transaction of this span.

Specified by:

createChildSpan in interface Span

Returns:

the new created child span, which must be transferred to another thread or another JVM before invoking Span.start() on it.

finishChildSpan

public void finishChildSpan(Span child)

Description copied from interface: Span

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.

Specified by:

finishChildSpan in interface Span

Parameters:

child - Child span to mark as finished.

finish

public void finish()

Description copied from interface: Span

Mark the span as successfully finished.

If it is the root span in the transaction or Span.finishChildSpan(Span) has been called for all of its children, then the transaction is finished as well. If there are child spans for which Span.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.

Specified by:

finish in interface Span

fail

public void fail(java.lang.Throwable t)

Description copied from interface: Span

Mark current span as finished with failure and associate the throwable as the root cause. This is equivalent to calling Span.fail(Throwable, boolean) with arguments fail(t, false).

Specified by:

fail in interface Span

Parameters:

t - Throwable to associate as root cause. Pass null if there is no exception to blame.

fail

public void fail(java.lang.Throwable t,
                 boolean failEntireTransaction)

Description copied from interface: Span

Mark current span as finished with failure and associate the throwable as the root cause.

Specified by:

fail in interface Span

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 Span.finishChildSpan(Span) by its parent, then the failure of the current span has no direct effect on the status of the transaction.