Class TelemetrySpan

java.lang.Object
com.codename1.telemetry.TelemetrySpan
public final class TelemetrySpan extends Object

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.

  • Field Details

    • KIND_INTERNAL

      public static final int KIND_INTERNAL
      An operation inside the app.
      See Also:

    • KIND_CLIENT

      public static final int KIND_CLIENT
      A request the app makes to something else.
      See Also:

  • 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.