Package io.honeycomb.beeline.tracing

Class Span

java.lang.Object

io.honeycomb.beeline.tracing.Span

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

SendingSpan, TracerSpan

public class Span
extends Object
implements AutoCloseable

A Span represents an operation over its duration and associates the attributes contained within this class with it. Subclasses of Span transparently implement the mechanism by which a Span is "closed" and submitted to Honeycomb.

Thread-safety

Instances of this class are not thread-safe.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Span()	Constructor that initialises this Span with "noop" data and sets the noop flag to true.
	Span(String spanName, String serviceName, String spanId, PropagationContext context, Map<String,?> fields, io.honeycomb.libhoney.transport.batch.ClockProvider clock)	Constructor that initialises the base Span data.

Method Summary

Modifier and Type	Method	Description
Span	addField(String key, Object value)	Add a field to the Span.
Span	addFields(Map<String,?> fieldsToAdd)	Add a fields to the Span.
Span	addTraceField(String key, Object value)	Add a trace field to the Span.
Span	addTraceFields(Map<String,?> traceFieldsToAdd)	Add trace fields to the Span.
void	close()	Closes this span in order to submit it as an Event to Honeycomb and perform any necessary clean up in the process.
protected void	closeInternal()	Subclasses should override this to implement the mechanism
double	elapsedTimeMs()
String	getDataset()
Map<String,Object>	getFields()
static Span	getNoopInstance()
String	getParentSpanId()
String	getServiceName()
String	getSpanId()
String	getSpanName()
long	getStartTime()
long	getTimestamp()
PropagationContext	getTraceContext()
Map<String,Object>	getTraceFields()
String	getTraceId()
boolean	isNoop()
Span	markStart()	Reset the Span's timer.
Span	markStart(long timestamp, long startTime)	Sets the times with the specified values - useful when copying Spans.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

Span

public Span(String spanName,
            String serviceName,
            String spanId,
            PropagationContext context,
            Map<String,?> fields,
            io.honeycomb.libhoney.transport.batch.ClockProvider clock)

Constructor that initialises the base Span data. It also calls markStart() immediately, which may be reset by client code by calling it any other point.

Parameters:

spanName - must not be empty.

serviceName - must not be empty.

spanId - must not be empty.

context - containing data about the trace - must not be null, and it must contain a traceId.

fields - may be null or empty.

clock - must not be null.

Span

protected Span()

Constructor that initialises this Span with "noop" data and sets the noop flag to true.

See Also:

noop

Method Detail

getNoopInstance

public static Span getNoopInstance()

isNoop

public boolean isNoop()

addField

public Span addField(String key,
                     Object value)

Add a field to the Span.

Parameters:

key - of the field.

value - of the field.

Returns:

this span.

addFields

public Span addFields(Map<String,?> fieldsToAdd)

Add a fields to the Span.

Parameters:

fieldsToAdd - to add.

Returns:

this Span.

addTraceField

public Span addTraceField(String key,
                          Object value)

Add a trace field to the Span.

Parameters:

key - of the field.

value - of the field.

Returns:

this Span.

addTraceFields

public Span addTraceFields(Map<String,?> traceFieldsToAdd)

Add trace fields to the Span.

Parameters:

traceFieldsToAdd - to add.

Returns:

this Span.

markStart

public Span markStart()

Reset the Span's timer.

The Span always starts the timer upon construction of the instance. However, if the operation covered by the Span starts later you can reset its timer with this (e.g. for async use cases).

Returns:

this Span.

markStart

public Span markStart(long timestamp,
                      long startTime)

Sets the times with the specified values - useful when copying Spans.

Parameters:

timestamp - (millis since the epoch)

startTime - start time (monotonic JVM time)

Returns:

this Span.

getParentSpanId

public String getParentSpanId()

getTraceId

public String getTraceId()

getDataset

public String getDataset()

getSpanId

public String getSpanId()

getSpanName

public String getSpanName()

getServiceName

public String getServiceName()

getFields

public Map<String,Object> getFields()

Returns:

an unmodifiable reference to the Span's fields.

See Also:

fields

getTraceFields

public Map<String,Object> getTraceFields()

Returns:

an unmodifiable reference to the Span's trace fields.

See Also:

traceFields

getTraceContext

public PropagationContext getTraceContext()

Returns:

a PropagationContext with the Span's IDs and trace fields - useful for propagating traces.

elapsedTimeMs

public double elapsedTimeMs()

Returns:

the time elapsed since "markStart" as a double with sub-millis in the fractional part.

See Also:

markStart()

getTimestamp

public long getTimestamp()

Returns:

the timestamp (millis since the epoch) of when "markStart" was called.

See Also:

markStart()

getStartTime

public long getStartTime()

Returns:

the start time (monotonic JVM time).

See Also:

markStart()

close

public void close()

Closes this span in order to submit it as an Event to Honeycomb and perform any necessary clean up in the process. Overrides of closeInternal() contain the logic to do this.

The Span's duration is measured upon calling this method (as per elapsedTimeMs()).

In order to avoid clashes, because of multiple events with the same span_id being submitted, this method ensures that it is only called once and ignores multiple invocations. However, it does not use any synchronization to ensure this and is therefore not thread safe.

This uses method allows Span to be used with try-with-resources statements.

Specified by:

close in interface AutoCloseable

closeInternal

protected void closeInternal()

Subclasses should override this to implement the mechanism

toString

public String toString()

Overrides:

toString in class Object