Package io.opentelemetry.sdk.trace

Class SdkSpanBuilder

    • Field Detail

      • spanName

        private final java.lang.String spanName

      • parent

        @Nullable
private Context parent

      • links

        @Nullable
private java.util.List<LinkData> links

      • totalNumberOfLinksAdded

        private int totalNumberOfLinksAdded

      • startEpochNanos

        private long startEpochNanos

    • Method Detail

      • addLink

        public ExtendedSpanBuilder addLink​(SpanContext spanContext)
        Description copied from interface: ExtendedSpanBuilder
        Adds a link to the newly created 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.

        Specified by:
        addLink in interface ExtendedSpanBuilder
        Specified by:
        addLink in interface SpanBuilder
        Parameters:
        spanContext - the context of the linked Span.
        Returns:
        this.

      • addLink

        public ExtendedSpanBuilder addLink​(SpanContext spanContext,
                                   Attributes attributes)
        Description copied from interface: ExtendedSpanBuilder
        Adds a link to the newly created 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.

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

      • addLink

        private void addLink​(LinkData link)

      • setAttribute

        public ExtendedSpanBuilder setAttribute​(java.lang.String key,
                                        java.lang.String value)
        Description copied from interface: ExtendedSpanBuilder
        Sets an attribute to the newly created Span. If SpanBuilder previously contained a mapping for the key, the old value is replaced by the specified value.

        If a null or empty String value is passed in, the behavior is undefined, and hence strongly discouraged.

        Note: It is strongly recommended to use SpanBuilder.setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

        Specified by:
        setAttribute in interface ExtendedSpanBuilder
        Specified by:
        setAttribute in interface SpanBuilder
        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.

      • setAttribute

        public <T> ExtendedSpanBuilder setAttribute​(AttributeKey<T> key,
                                            T value)
        Description copied from interface: ExtendedSpanBuilder
        Sets an attribute to the newly created Span. If SpanBuilder 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 ExtendedSpanBuilder
        Specified by:
        setAttribute in interface SpanBuilder
        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.

      • setStartTimestamp

        public ExtendedSpanBuilder setStartTimestamp​(long startTimestamp,
                                             java.util.concurrent.TimeUnit unit)
        Description copied from interface: ExtendedSpanBuilder
        Sets an explicit start timestamp for the newly created Span.

        LIRInstruction.Use this method to specify an explicit start timestamp. If not called, the implementation will use the timestamp value at SpanBuilder.startSpan() time, which should be the default case.

        Important this is NOT equivalent with System.nanoTime().

        Specified by:
        setStartTimestamp in interface ExtendedSpanBuilder
        Specified by:
        setStartTimestamp in interface SpanBuilder
        Parameters:
        startTimestamp - the explicit start timestamp from the epoch of the newly created Span.
        unit - the unit of the timestamp.
        Returns:
        this.

      • startSpan

        public Span startSpan()
        Description copied from interface: SpanBuilder
        Starts a new Span.

        Users must manually call Span.end() to end this Span.

        Does not install the newly created Span to the current Context.

        IMPORTANT: This method can be called only once per SpanBuilder instance and as the last method called. After this method is called calling any method is undefined behavior.

        Example of usage: 

        
 class MyClass {
   private final Tracer tracer;

   MyClass(OpenTelemetry openTelemetry) {
     tracer = openTelemetry.getTracer("com.example.rpc");
   }

   void doWork(Span parent) {
     Span childSpan = tracer.spanBuilder("MyChildSpan")
          .setParent(Context.current().with(parent))
          .startSpan();
     childSpan.addEvent("my event");
     try {
       doSomeWork(childSpan); // Manually propagate the new span down the stack.
     } finally {
       // To make sure we end the span even in case of an exception.
       childSpan.end();  // Manually end the span.
     }
   }
 }
        Specified by:
        startSpan in interface SpanBuilder
        Returns:
        the newly created Span.

      • startAndCall

        public <T,​E extends java.lang.Throwable> T startAndCall​(SpanCallable<T,​E> spanCallable)
                                                       throws E extends java.lang.Throwable
        Description copied from interface: ExtendedSpanBuilder
        Runs the given SpanCallable inside of the span created by the given SpanBuilder. The span will be ended at the end of the SpanCallable.

        If an exception is thrown by the SpanCallable, the span will be marked as error, and the exception will be recorded.

        Specified by:
        startAndCall in interface ExtendedSpanBuilder
        Type Parameters:
        T - the type of the result
        E - the type of the exception
        Parameters:
        spanCallable - the SpanCallable to call
        Returns:
        the result of the SpanCallable
        Throws:
        E extends java.lang.Throwable

      • startAndCall

        public <T,​E extends java.lang.Throwable> T startAndCall​(SpanCallable<T,​E> spanCallable,
                                                              java.util.function.BiConsumer<Span,​java.lang.Throwable> handleException)
                                                       throws E extends java.lang.Throwable
        Description copied from interface: ExtendedSpanBuilder
        Runs the given SpanCallable inside of the span created by the given SpanBuilder. The span will be ended at the end of the SpanCallable.

        If an exception is thrown by the SpanCallable, the handleException consumer will be called, giving you the opportunity to handle the exception and span in a custom way, e.g. not marking the span as error.

        Specified by:
        startAndCall in interface ExtendedSpanBuilder
        Type Parameters:
        T - the type of the result
        E - the type of the exception
        Parameters:
        spanCallable - the SpanCallable to call
        handleException - the consumer to call when an exception is thrown
        Returns:
        the result of the SpanCallable
        Throws:
        E extends java.lang.Throwable

      • startAndRun

        public <E extends java.lang.Throwable> void startAndRun​(SpanRunnable<E> runnable)
                                                 throws E extends java.lang.Throwable
        Description copied from interface: ExtendedSpanBuilder
        Runs the given SpanRunnable inside of the span created by the given SpanBuilder. The span will be ended at the end of the SpanRunnable.

        If an exception is thrown by the SpanRunnable, the span will be marked as error, and the exception will be recorded.

        Specified by:
        startAndRun in interface ExtendedSpanBuilder
        Type Parameters:
        E - the type of the exception
        Parameters:
        runnable - the SpanRunnable to run
        Throws:
        E extends java.lang.Throwable

      • startAndRun

        public <E extends java.lang.Throwable> void startAndRun​(SpanRunnable<E> runnable,
                                                        java.util.function.BiConsumer<Span,​java.lang.Throwable> handleException)
                                                 throws E extends java.lang.Throwable
        Description copied from interface: ExtendedSpanBuilder
        Runs the given SpanRunnable inside of the span created by the given SpanBuilder. The span will be ended at the end of the SpanRunnable.

        If an exception is thrown by the SpanRunnable, the handleException consumer will be called, giving you the opportunity to handle the exception and span in a custom way, e.g. not marking the span as error.

        Specified by:
        startAndRun in interface ExtendedSpanBuilder
        Type Parameters:
        E - the type of the exception
        Parameters:
        runnable - the SpanRunnable to run
        Throws:
        E extends java.lang.Throwable

      • setSpanError

        private static void setSpanError​(Span span,
                                 java.lang.Throwable exception)
        Marks a span as error. This is the default exception handler.
        Parameters:
        span - the span
        exception - the exception that caused the error