Class SdkSpan

    • Field Detail

      • logger

        private static final java.util.logging.Logger logger
      • parentSpanContext

        private final SpanContext parentSpanContext
      • resource

        private final Resource resource
      • startEpochNanos

        private final long startEpochNanos
      • lock

        private final java.lang.Object lock
      • name

        private java.lang.String name
      • events

        @Nullable
        private java.util.List<EventData> events
      • totalRecordedEvents

        private int totalRecordedEvents
      • links

        @Nullable
        java.util.List<LinkData> links
      • totalRecordedLinks

        private int totalRecordedLinks
      • endEpochNanos

        private long endEpochNanos
      • EXCEPTION_TYPE

        private static final AttributeKey<java.lang.String> EXCEPTION_TYPE
      • EXCEPTION_MESSAGE

        private static final AttributeKey<java.lang.String> EXCEPTION_MESSAGE
      • EXCEPTION_STACKTRACE

        private static final AttributeKey<java.lang.String> EXCEPTION_STACKTRACE
    • Method Detail

      • startSpan

        static SdkSpan startSpan​(SpanContext context,
                                 java.lang.String name,
                                 InstrumentationScopeInfo instrumentationScopeInfo,
                                 SpanKind kind,
                                 Span parentSpan,
                                 Context parentContext,
                                 SpanLimits spanLimits,
                                 SpanProcessor spanProcessor,
                                 Clock tracerClock,
                                 Resource resource,
                                 @Nullable
                                 AttributesMap attributes,
                                 @Nullable
                                 java.util.List<LinkData> links,
                                 int totalRecordedLinks,
                                 long userStartEpochNanos)
        Creates and starts a span with the given configuration.
        Parameters:
        context - supplies the trace_id and span_id for the newly started span.
        name - the displayed name for the new span.
        kind - the span kind.
        parentSpan - the parent span, or Span.getInvalid() if this span is a root span.
        spanLimits - limits applied to this span.
        spanProcessor - handler called when the span starts and ends.
        tracerClock - the tracer's clock
        resource - the resource associated with this span.
        attributes - the attributes set during span creation.
        links - the links set during span creation, may be truncated. The list MUST be immutable.
        Returns:
        a new and started span.
      • toSpanData

        public SpanData toSpanData()
        Description copied from interface: ReadableSpan
        This converts this instance into an immutable SpanData instance, for use in export.
        Specified by:
        toSpanData in interface ReadableSpan
        Returns:
        an immutable SpanData instance.
      • hasEnded

        public boolean hasEnded()
        Description copied from interface: ReadableSpan
        Returns whether this Span has already been ended.

        Note: the implementation of this method performs locking to ensure thread-safe behavior.

        Specified by:
        hasEnded in interface ReadableSpan
        Returns:
        true if the span has already been ended, false if not.
      • getSpanContext

        public SpanContext getSpanContext()
        Description copied from interface: Span
        Returns the SpanContext associated with this Span.
        Specified by:
        getSpanContext in interface ReadableSpan
        Specified by:
        getSpanContext in interface Span
        Returns:
        the SpanContext associated with this Span.
      • getName

        public java.lang.String getName()
        Returns the name of the Span.
        Specified by:
        getName in interface ReadableSpan
        Returns:
        the name of the Span.
      • getLatencyNanos

        public long getLatencyNanos()
        Returns the latency of the Span in nanos. If still active then returns now() - start time.
        Specified by:
        getLatencyNanos in interface ReadableSpan
        Returns:
        the latency of the Span in nanos.
      • setAttribute

        public <T> ReadWriteSpan setAttribute​(AttributeKey<T> key,
                                              T value)
        Description copied from interface: Span
        Sets an attribute to the Span. If the Span previously contained a mapping for the key, the old value is replaced by the specified value.

        Note: the behavior of null values is undefined, and hence strongly discouraged.

        Specified by:
        setAttribute in interface Span
        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.
      • isModifiableByCurrentThread

        private boolean isModifiableByCurrentThread()
      • addEvent

        public ReadWriteSpan addEvent​(java.lang.String name)
        Description copied from interface: Span
        Adds an event to the Span. The timestamp of the event will be the current time.
        Specified by:
        addEvent in interface Span
        Parameters:
        name - the name of the event.
        Returns:
        this.
      • addEvent

        public ReadWriteSpan addEvent​(java.lang.String name,
                                      long timestamp,
                                      java.util.concurrent.TimeUnit unit)
        Description copied from interface: Span
        Adds an event to the Span with the given timestamp, as nanos since epoch. Note, this timestamp is not the same as System.nanoTime() but may be computed using it, for example, by taking a difference of readings from System.nanoTime() and adding to the span start time.

        When possible, it is preferred to use Span.addEvent(String) at the time the event occurred.

        Specified by:
        addEvent in interface Span
        Parameters:
        name - the name of the event.
        timestamp - the explicit event timestamp since epoch.
        unit - the unit of the timestamp
        Returns:
        this.
      • addEvent

        public ReadWriteSpan addEvent​(java.lang.String name,
                                      Attributes attributes)
        Description copied from interface: Span
        Adds an event to the Span with the given Attributes. The timestamp of the event will be the current time.
        Specified by:
        addEvent in interface Span
        Parameters:
        name - the name of the event.
        attributes - the attributes that will be added; these are associated with this event, not the Span as for setAttribute().
        Returns:
        this.
      • addEvent

        public ReadWriteSpan addEvent​(java.lang.String name,
                                      Attributes attributes,
                                      long timestamp,
                                      java.util.concurrent.TimeUnit unit)
        Description copied from interface: Span
        Adds an event to the Span with the given Attributes and timestamp. Note, this timestamp is not the same as System.nanoTime() but may be computed using it, for example, by taking a difference of readings from System.nanoTime() and adding to the span start time.

        When possible, it is preferred to use Span.addEvent(String) at the time the event occurred.

        Specified by:
        addEvent in interface Span
        Parameters:
        name - the name of the event.
        attributes - the attributes that will be added; these are associated with this event, not the Span as for setAttribute().
        timestamp - the explicit event timestamp since epoch.
        unit - the unit of the timestamp
        Returns:
        this.
      • addTimedEvent

        private void addTimedEvent​(EventData timedEvent)
      • setStatus

        public ReadWriteSpan setStatus​(StatusCode statusCode,
                                       @Nullable
                                       java.lang.String description)
        Description copied from interface: Span
        Sets the status to the Span.

        If used, this will override the default Span status. Default status code is StatusCode.UNSET.

        Only the value of the last call will be recorded, and implementations are free to ignore previous calls.

        Specified by:
        setStatus in interface Span
        Parameters:
        statusCode - the StatusCode to set.
        description - the description of the Status.
        Returns:
        this.
      • recordException

        public ReadWriteSpan recordException​(java.lang.Throwable exception)
        Description copied from interface: Span
        Records information about the Throwable to the Span.

        Note that the EXCEPTION_ESCAPED value from the Semantic Conventions cannot be determined by this function. You should record this attribute manually using Span.recordException(Throwable, Attributes) if you know that an exception is escaping.

        Specified by:
        recordException in interface Span
        Parameters:
        exception - the Throwable to record.
        Returns:
        this.
      • recordException

        public ReadWriteSpan recordException​(java.lang.Throwable exception,
                                             Attributes additionalAttributes)
        Description copied from interface: Span
        Records information about the Throwable to the Span.
        Specified by:
        recordException in interface Span
        Parameters:
        exception - the Throwable to record.
        additionalAttributes - the additional Attributes to record.
        Returns:
        this.
      • updateName

        public ReadWriteSpan updateName​(java.lang.String name)
        Description copied from interface: Span
        Updates the Span name.

        If used, this will override the name provided via Span.Builder.

        Upon this update, any sampling behavior based on Span name will depend on the implementation.

        Specified by:
        updateName in interface Span
        Parameters:
        name - the Span name.
        Returns:
        this.
      • addLink

        public Span addLink​(SpanContext spanContext,
                            Attributes attributes)
        Description copied from interface: Span
        Adds a link to this Span.

        Links are used to link Spans in different traces. Used (for example) in batching operations, where a single batch handler processes multiple requests from different traces or the same trace.

        Implementations may ignore calls with an invalid span context.

        Callers should prefer to add links before starting the span via SpanBuilder.addLink(SpanContext, Attributes) if possible.

        Specified by:
        addLink in interface Span
        Parameters:
        spanContext - the context of the linked Span.
        attributes - the attributes of the Link.
        Returns:
        this.
      • end

        public void end()
        Description copied from interface: Span
        Marks the end of Span execution.

        Only the timing of the first end call for a given Span will be recorded, and implementations are free to ignore all further calls.

        Specified by:
        end in interface Span
      • end

        public void end​(long timestamp,
                        java.util.concurrent.TimeUnit unit)
        Description copied from interface: Span
        Marks the end of Span execution with the specified timestamp.

        Only the timing of the first end call for a given Span will be recorded, and implementations are free to ignore all further calls.

        Use this method for specifying explicit end options, such as end Timestamp. When no explicit values are required, use Span.end().

        Specified by:
        end in interface Span
        Parameters:
        timestamp - the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.
        unit - the unit of the timestamp
      • endInternal

        private void endInternal​(long endEpochNanos)
      • getKind

        public SpanKind getKind()
        Description copied from interface: ReadableSpan
        Returns the kind of the span.
        Specified by:
        getKind in interface ReadableSpan
        Returns:
        the kind of the span.
      • getStartEpochNanos

        long getStartEpochNanos()
      • getImmutableTimedEvents

        private java.util.List<EventData> getImmutableTimedEvents()
      • getImmutableAttributes

        private Attributes getImmutableAttributes()
      • getImmutableLinks

        private java.util.List<LinkData> getImmutableLinks()
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object