public final class TelemetrySpan

Object
TelemetrySpan

One timed operation in a distributed trace.

Network requests become spans by themselves once Telemetry is installed; an app creates its own with Telemetry.startSpan(String) or Telemetry.run(String, Runnable) to time something the user did – a tap, a screen load – so the requests it caused are grouped under it.

A span the sampler declined is not recorded, but it still carries its trace context, and propagates the decision: the backend it calls agrees not to record either, so a trace is whole or absent rather than missing its middle.

Not thread safe. A span belongs to the thread doing the work it times, and is handed to the exporter only when it ends.

Fields

`public static final int KIND_INTERNAL = 1`	An operation inside the app.
`public static final int KIND_CLIENT = 3`	A request the app makes to something else.

Methods

`public` `TelemetrySpan setAttribute(String key, String value)`	Adds or replaces a string attribute.
`public` `TelemetrySpan setAttribute(String key, long value)`	Adds or replaces an integer attribute.
`public` `TelemetrySpan setAttribute(String key, double value)`	Adds or replaces a floating point attribute.
`public` `TelemetrySpan setAttribute(String key, boolean value)`	Adds or replaces a flag attribute.
`public` `TelemetrySpan recordException(Throwable error)`	Records a failure as an “exception” event and marks the span failed.
`public` `TelemetrySpan setError(String description)`	Marks the span failed, with a short description.
`public` `TelemetrySpan updateName(String newName)`	Renames the span.
`public` `String getName()`	The span’s name.
`public boolean isRecording()`	Whether this span is recorded.
`public` `String getTraceId()`	The 32 hex digit trace id.
`public` `String getSpanId()`	The 16 hex digit span id.
`public` `String getTraceparent()`	This span as a W3C `traceparent` header value, for a transport the framework does not instrument itself – a WebSocket message, a push token registration.
`public void end()`	Ends the span.

Inherited methods

From Object

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

Field details

KIND_INTERNAL

public static final int KIND_INTERNAL = 1

An operation inside the app.

KIND_CLIENT

public static final int KIND_CLIENT = 3

A request the app makes to something else.

Method details

setAttribute

public TelemetrySpan setAttribute(String key, String value)

Adds or replaces a string attribute. Null values are ignored.

Returns

this span

setAttribute

public TelemetrySpan setAttribute(String key, long value)

Adds or replaces an integer attribute.

Returns

this span

setAttribute

public TelemetrySpan setAttribute(String key, double value)

Adds or replaces a floating point attribute. NaN and the infinities, which JSON cannot spell, are recorded as text.

Returns

this span

setAttribute

public TelemetrySpan setAttribute(String key, boolean value)

Adds or replaces a flag attribute.

Returns

this span

recordException

public TelemetrySpan recordException(Throwable error)

Records a failure as an “exception” event and marks the span failed. The message is kept; the stack trace is not.

Returns

this span

setError

public TelemetrySpan setError(String description)

Marks the span failed, with a short description.

Returns

this span

updateName

public TelemetrySpan updateName(String newName)

Renames the span.

Returns

this span

getName

public String getName()

The span’s name.

isRecording

public boolean isRecording()

Whether this span is recorded. Attributes set on one that is not go nowhere, so an attribute that is expensive to compute can be skipped.

getTraceId

public String getTraceId()

The 32 hex digit trace id.

getSpanId

public String getSpanId()

The 16 hex digit span id.

getTraceparent

public String getTraceparent()

This span as a W3C traceparent header value, for a transport the framework does not instrument itself – a WebSocket message, a push token registration.

Null for the span Telemetry.startSpan(String) hands out when there is no trace to join: telemetry is not installed, consent is required and not given, or the platform cannot make ids. Its ids are all zeros, which W3C Trace Context defines as invalid, so a header built from them would be refused or misread downstream. An unsampled span is different: it is a real trace whose decision must travel, and it answers with its -00 flags.

Returns

the header value, or null when there is no trace

end

public void end()

Ends the span. Only the first call counts.