Package io.opentelemetry.api.incubator.trace

Interface ExtendedSpanBuilder

All Superinterfaces:
SpanBuilder
All Known Implementing Classes:
ExtendedDefaultTracer.NoopSpanBuilder, SdkSpanBuilder
public interface ExtendedSpanBuilder extends SpanBuilder
Extended SpanBuilder with experimental APIs.

  • Method Details

    • setParentFrom

      ExtendedSpanBuilder setParentFrom(ContextPropagators propagators, Map<String,String> carrier)
      Extract a span context from the given carrier and set it as parent of the span for startAndCall(SpanCallable) and startAndRun(SpanRunnable).

      The span context will be extracted from the carrier, which you usually get from HTTP headers of the metadata of a message you're processing.

      Parameters:
      propagators - provide the propagators from OpenTelemetry.getPropagators()
      carrier - the string map where to extract the span context from

    • startAndCall

      <T, E extends Throwable> T startAndCall(SpanCallable<T,E> spanCallable) throws E
      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.

      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

    • startAndCall

      <T, E extends Throwable> T startAndCall(SpanCallable<T,E> spanCallable, BiConsumer<Span,Throwable> handleException) throws E
      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.

      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

    • startAndRun

      <E extends Throwable> void startAndRun(SpanRunnable<E> runnable) throws E
      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.

      Type Parameters:
      E - the type of the exception
      Parameters:
      runnable - the SpanRunnable to run
      Throws:
      E

    • startAndRun

      <E extends Throwable> void startAndRun(SpanRunnable<E> runnable, BiConsumer<Span,Throwable> handleException) throws E
      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.

      Type Parameters:
      E - the type of the exception
      Parameters:
      runnable - the SpanRunnable to run
      Throws:
      E

    • setParent

      ExtendedSpanBuilder setParent(Context context)
      Sets the parent to use from the specified Context. If not set, the value of Span.current() at SpanBuilder.startSpan() time will be used as parent.

      If no Span is available in the specified Context, the resulting Span will become a root instance, as if SpanBuilder.setNoParent() had been called.

      If called multiple times, only the last specified value will be used. Observe that the state defined by a previous call to SpanBuilder.setNoParent() will be discarded.

      Specified by:
      setParent in interface SpanBuilder
      Parameters:
      context - the Context.
      Returns:
      this.

    • setNoParent

      ExtendedSpanBuilder setNoParent()
      Sets the option to become a root Span for a new trace. If not set, the value of Span.current() at SpanBuilder.startSpan() time will be used as parent.

      Observe that any previously set parent will be discarded.

      Specified by:
      setNoParent in interface SpanBuilder
      Returns:
      this.

    • addLink

      ExtendedSpanBuilder addLink(SpanContext spanContext)
      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 SpanBuilder
      Parameters:
      spanContext - the context of the linked Span.
      Returns:
      this.

    • addLink

      ExtendedSpanBuilder addLink(SpanContext spanContext, Attributes attributes)
      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 SpanBuilder
      Parameters:
      spanContext - the context of the linked Span.
      attributes - the attributes of the Link.
      Returns:
      this.

    • setAttribute

      ExtendedSpanBuilder setAttribute(String key, String value)
      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 SpanBuilder
      Parameters:
      key - the key for this attribute.
      value - the value for this attribute.
      Returns:
      this.

    • setAttribute

      ExtendedSpanBuilder setAttribute(String key, long value)
      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: It is strongly recommended to use SpanBuilder.setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

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

    • setAttribute

      ExtendedSpanBuilder setAttribute(String key, double value)
      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: It is strongly recommended to use SpanBuilder.setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

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

    • setAttribute

      ExtendedSpanBuilder setAttribute(String key, boolean value)
      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: It is strongly recommended to use SpanBuilder.setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

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

    • setAttribute

      <T> ExtendedSpanBuilder setAttribute(AttributeKey<T> key, T value)
      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 SpanBuilder
      Parameters:
      key - the key for this attribute.
      value - the value for this attribute.
      Returns:
      this.

    • setAllAttributes

      default ExtendedSpanBuilder setAllAttributes(Attributes attributes)
      Sets attributes to the SpanBuilder. If the SpanBuilder previously contained a mapping for any of the keys, the old values are replaced by the specified values.
      Specified by:
      setAllAttributes in interface SpanBuilder
      Parameters:
      attributes - the attributes
      Returns:
      this.

    • setSpanKind

      ExtendedSpanBuilder setSpanKind(SpanKind spanKind)
      Sets the SpanKind for the newly created Span. If not called, the implementation will provide a default value SpanKind.INTERNAL.
      Specified by:
      setSpanKind in interface SpanBuilder
      Parameters:
      spanKind - the kind of the newly created Span.
      Returns:
      this.

    • setStartTimestamp

      ExtendedSpanBuilder setStartTimestamp(long startTimestamp, TimeUnit unit)
      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 SpanBuilder
      Parameters:
      startTimestamp - the explicit start timestamp from the epoch of the newly created Span.
      unit - the unit of the timestamp.
      Returns:
      this.

    • setStartTimestamp

      default ExtendedSpanBuilder setStartTimestamp(Instant startTimestamp)
      Sets an explicit start timestamp for the newly created Span.

      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 SpanBuilder
      Parameters:
      startTimestamp - the explicit start timestamp from the epoch of the newly created Span.
      Returns:
      this.