Class Span

java.lang.Object
com.codename1.backend.Span
public abstract class Span extends Object

One timed operation inside a distributed trace.

The server creates these itself -- one per request, one per outbound Web call and one per Database statement -- so an application normally only touches the current one, through Tracing.current(), to add an attribute. Tracing.inSpan(String, Tracing.Work) wraps a block of its own work.

When tracing is not installed every method here is a no-op on a shared instance, so code that decorates the current span costs nothing in a server that does not export traces.

The kinds and status codes are the numbers the OTLP wire format uses, so a tracer can write them without translating.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    KIND_CLIENT
    A request this process makes to something else.
    static final int
    KIND_INTERNAL
    An operation inside the process.
    static final int
    KIND_SERVER
    Answering a request that arrived from outside.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Span()
    For tracer implementations.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract void
    discard()
    Drops the span: it ends normally but is never exported.
    abstract void
    end()
    Ends the span.
    abstract int
    getKind()
    One of the KIND constants.
    abstract String
    getName()
    The current name.
    abstract boolean
    isRecording()
    Whether this span is being recorded.
    abstract Span
    recordException(Throwable error)
    Records a failure as an "exception" event and marks the span as an error.
    abstract Span
    setAttribute(String key, boolean value)
    Adds or replaces a flag attribute.
    abstract Span
    setAttribute(String key, double value)
    Adds or replaces a floating point attribute.
    abstract Span
    setAttribute(String key, long value)
    Adds or replaces an integer attribute.
    abstract Span
    setAttribute(String key, String value)
    Adds or replaces a string attribute.
    abstract Span
    setError(String description)
    Marks the span as failed, with a short description.
    abstract String
    traceparent()
    This span as a W3C traceparent value, which is what an outbound request carries so the service it reaches joins the same trace.
    abstract String
    tracestate()
    The W3C tracestate this trace carries, or null for none.
    abstract Span
    updateName(String name)
    Renames the span.

    Methods inherited from class Object

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

  • Field Details

    • KIND_INTERNAL

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

    • KIND_SERVER

      public static final int KIND_SERVER
      Answering a request that arrived from outside.
      See Also:

    • KIND_CLIENT

      public static final int KIND_CLIENT
      A request this process makes to something else.
      See Also:

  • Constructor Details

    • Span

      protected Span()
      For tracer implementations.

  • Method Details

    • setAttribute

      public abstract Span setAttribute(String key, String value)
      Adds or replaces a string attribute. A null value is ignored.

    • setAttribute

      public abstract Span setAttribute(String key, long value)
      Adds or replaces an integer attribute.

    • setAttribute

      public abstract Span setAttribute(String key, double value)
      Adds or replaces a floating point attribute.

    • setAttribute

      public abstract Span setAttribute(String key, boolean value)
      Adds or replaces a flag attribute.

    • recordException

      public abstract Span recordException(Throwable error)
      Records a failure as an "exception" event and marks the span as an error. The message is kept; the stack trace is not, because it can carry values a handler had in scope and it is by far the largest part of a span.

    • setError

      public abstract Span setError(String description)
      Marks the span as failed, with a short description.

    • updateName

      public abstract Span updateName(String name)
      Renames the span. The router calls this once it knows the route template.

    • getName

      public abstract String getName()
      The current name.

    • getKind

      public abstract int getKind()
      One of the KIND constants.

    • isRecording

      public abstract boolean isRecording()
      Whether this span is being recorded. A span the sampler declined still carries a trace context and propagates it, so the NEXT service agrees not to record either -- but attributes set on it go nowhere, and a caller that would compute an expensive one can ask first.

    • traceparent

      public abstract String traceparent()
      This span as a W3C traceparent value, which is what an outbound request carries so the service it reaches joins the same trace. Null for the no-op span.

    • tracestate

      public abstract String tracestate()
      The W3C tracestate this trace carries, or null for none.

    • discard

      public abstract void discard()
      Drops the span: it ends normally but is never exported. For traffic that is about tracing itself, which would otherwise report on every export.

    • end

      public abstract void end()
      Ends the span. Only the first call counts.