Class AbstractSpan<T extends AbstractSpan<T>>

  • All Implemented Interfaces:
    Recyclable
    Direct Known Subclasses:
    Span, Transaction

    public abstract class AbstractSpan<T extends AbstractSpan<T>>
    extends java.lang.Object
    implements Recyclable
    • Field Detail

      • PRIO_HIGH_LEVEL_FRAMEWORK

        public static final int PRIO_HIGH_LEVEL_FRAMEWORK
        See Also:
        Constant Field Values
      • PRIO_LOW_LEVEL_FRAMEWORK

        public static final int PRIO_LOW_LEVEL_FRAMEWORK
        See Also:
        Constant Field Values
      • MS_IN_MICROS

        protected static final double MS_IN_MICROS
      • name

        protected final java.lang.StringBuilder name
        Generic designation of a transaction in the scope of a single service (eg: 'GET /users/:id')
      • collectBreakdownMetrics

        protected final boolean collectBreakdownMetrics
      • duration

        protected long duration
      • references

        protected java.util.concurrent.atomic.AtomicInteger references
      • finished

        protected volatile boolean finished
    • Method Detail

      • getReferenceCount

        public int getReferenceCount()
      • requestDiscarding

        public T requestDiscarding()
        Requests this span to be discarded, even if it's sampled.

        Whether the span can actually be discarded is determined by isDiscarded()

      • isDiscarded

        public boolean isDiscarded()
        Determines whether to discard the span. Only spans that return false are reported.

        A span is discarded if it is discardable and requested to be discarded.

        Returns:
        true, if the span should be discarded, false otherwise.
      • getTransaction

        @Nullable
        public abstract Transaction getTransaction()
      • isReferenced

        public boolean isReferenced()
      • isFinished

        public boolean isFinished()
      • getDuration

        public long getDuration()
        How long the transaction took to complete, in µs
      • getSelfDuration

        public long getSelfDuration()
      • getDurationMs

        public double getDurationMs()
      • getNameForSerialization

        public java.lang.StringBuilder getNameForSerialization()
        Only intended to be used by DslJsonSerializer
      • getAndOverrideName

        @Nullable
        public java.lang.StringBuilder getAndOverrideName​(int namePriority)
        Resets and returns the name StringBuilder if the provided priority is >= namePriority one. Otherwise, returns null
        Parameters:
        namePriority - the priority for the name. See also the AbstractSpan#PRIO_* constants.
        Returns:
        the name StringBuilder if the provided priority is >= namePriority, null otherwise.
      • getAndOverrideName

        @Nullable
        public java.lang.StringBuilder getAndOverrideName​(int namePriority,
                                                          boolean overrideIfSamePriority)
        Resets and returns the name StringBuilder if one of the following applies: Otherwise, returns null
        Parameters:
        namePriority - the priority for the name. See also the AbstractSpan#PRIO_* constants.
        overrideIfSamePriority - specifies whether the existing name should be overridden if namePriority equals the priority used to set the current name
        Returns:
        the name StringBuilder if the provided priority is sufficient for overriding, null otherwise.
      • getNameAsString

        public java.lang.String getNameAsString()
        Only intended for testing purposes as this allocates a String
        Returns:
        name
      • appendToName

        public T appendToName​(java.lang.CharSequence cs)
        Appends a string to the name.

        This method helps to avoid the memory allocations of string concatenations as the underlying StringBuilder instance will be reused.

        Parameters:
        cs - the char sequence to append to the name
        Returns:
        this, for chaining
      • appendToName

        public T appendToName​(java.lang.CharSequence cs,
                              int priority)
      • withName

        public T withName​(@Nullable
                          java.lang.String name)
      • withName

        public T withName​(@Nullable
                          java.lang.String name,
                          int priority)
      • withName

        public T withName​(@Nullable
                          java.lang.String name,
                          int priority,
                          boolean overrideIfSamePriority)
      • getTimestamp

        public long getTimestamp()
        Recorded time of the span or transaction in microseconds since epoch
      • resetState

        public void resetState()
        Description copied from interface: Recyclable
        resets pooled object state so it can be reused
        Specified by:
        resetState in interface Recyclable
      • createSpan

        public Span createSpan()
      • createSpan

        public Span createSpan​(long epochMicros)
      • createExitSpan

        @Nullable
        public Span createExitSpan()
        Creates a child Span representing a remote call event, unless this TraceContextHolder already represents an exit event. If current TraceContextHolder is representing an Exit- returns null
        Returns:
        an Exit span if this TraceContextHolder is not an exit span, null otherwise
      • asExit

        public T asExit()
      • isExit

        public boolean isExit()
      • captureException

        public void captureException​(long epochMicros,
                                     java.lang.Throwable t)
      • captureException

        public T captureException​(@Nullable
                                  java.lang.Throwable t)
      • endExceptionally

        public void endExceptionally​(@Nullable
                                     java.lang.Throwable t)
      • captureExceptionAndGetErrorId

        @Nullable
        public java.lang.String captureExceptionAndGetErrorId​(@Nullable
                                                              java.lang.Throwable t)
      • addLabel

        public void addLabel​(java.lang.String key,
                             java.lang.String value)
      • addLabel

        public void addLabel​(java.lang.String key,
                             java.lang.Number value)
      • addLabel

        public void addLabel​(java.lang.String key,
                             java.lang.Boolean value)
      • onAfterStart

        protected void onAfterStart()
        Called after the span has been started and its parent references are set
      • end

        public void end()
      • end

        public final void end​(long epochMicros)
      • outcomeNotSet

        protected boolean outcomeNotSet()
        Returns:
        true if outcome has NOT been set, either by user or through instrumentation
      • hasCapturedExceptions

        protected boolean hasCapturedExceptions()
        Returns:
        true if an exception has been captured
      • beforeEnd

        protected abstract void beforeEnd​(long epochMicros)
      • afterEnd

        protected abstract void afterEnd()
      • isChildOf

        public boolean isChildOf​(AbstractSpan<?> parent)
      • activate

        public T activate()
      • deactivate

        public T deactivate()
      • activateInScope

        public Scope activateInScope()
      • setStartTimestamp

        public void setStartTimestamp​(long epochMicros)
        Set start timestamp
        Parameters:
        epochMicros - start timestamp in micro-seconds since epoch
      • setStartTimestampNow

        public void setStartTimestampNow()
        Set start timestamp from context current clock
      • incrementReferences

        public void incrementReferences()
      • decrementReferences

        public void decrementReferences()
      • recycle

        protected abstract void recycle()
      • propagateTraceContext

        public <C> void propagateTraceContext​(C carrier,
                                              TextHeaderSetter<C> headerSetter)
        Sets Trace context text headers, using this context as parent, on the provided carrier using the provided setter
        Type Parameters:
        C - the header carrier type, for example - an HTTP request
        Parameters:
        carrier - the text headers carrier
        headerSetter - a setter implementing the actual addition of headers to the headers carrier
      • propagateTraceContext

        public <C> boolean propagateTraceContext​(C carrier,
                                                 BinaryHeaderSetter<C> headerSetter)
        Sets Trace context binary headers, using this context as parent, on the provided carrier using the provided setter
        Type Parameters:
        C - the header carrier type, for example - a Kafka record
        Parameters:
        carrier - the binary headers carrier
        headerSetter - a setter implementing the actual addition of headers to the headers carrier
        Returns:
        true if Trace Context headers were set; false otherwise
      • setNonDiscardable

        public void setNonDiscardable()
        Sets this context as non-discardable, meaning that isDiscarded() will return false, even if requestDiscarding() has been called.
      • isDiscardable

        public boolean isDiscardable()
        Returns whether it's possible to discard this span.
        Returns:
        true, if it's safe to discard the span, false otherwise.
      • isSampled

        public boolean isSampled()
      • withChildIds

        public T withChildIds​(@Nullable
                              LongList childIds)
      • getChildIds

        @Nullable
        public LongList getChildIds()
      • thiz

        protected abstract T thiz()
      • getOutcome

        public Outcome getOutcome()
        Returns:
        user outcome if set, otherwise outcome value
      • withOutcome

        public T withOutcome​(Outcome outcome)
        Sets outcome
        Parameters:
        outcome - outcome
        Returns:
        this
      • withUserOutcome

        public T withUserOutcome​(Outcome outcome)
        Sets user outcome, which has priority over outcome set through withOutcome(Outcome)
        Parameters:
        outcome - user outcome
        Returns:
        this