Class SdkSpanBuilder

java.lang.Object

io.opentelemetry.sdk.trace.SdkSpanBuilder

All Implemented Interfaces:

ExtendedSpanBuilder, SpanBuilder

final class SdkSpanBuilder
extends Object
implements ExtendedSpanBuilder

SdkSpanBuilder is SDK implementation of SpanBuilder.

Field Summary

Fields

Modifier and Type	Field	Description
private AttributesMap	attributes
private final InstrumentationScopeInfo	instrumentationScopeInfo
private List<LinkData>	links
private Context	parent
private SpanKind	spanKind
private final SpanLimits	spanLimits
private final String	spanName
private long	startEpochNanos
private int	totalNumberOfLinksAdded
private final TracerSharedState	tracerSharedState

Constructor Summary

Constructors

Constructor	Description
SdkSpanBuilder(String spanName, InstrumentationScopeInfo instrumentationScopeInfo, TracerSharedState tracerSharedState, SpanLimits spanLimits)

Method Summary

Modifier and Type	Method	Description
ExtendedSpanBuilder	addLink(SpanContext spanContext)	Adds a link to the newly created Span.
ExtendedSpanBuilder	addLink(SpanContext spanContext, Attributes attributes)	Adds a link to the newly created Span.
private void	addLink(LinkData link)
private AttributesMap	attributes()
(package private) static boolean	isRecording(SamplingDecision decision)
(package private) static boolean	isSampled(SamplingDecision decision)
<T> ExtendedSpanBuilder	setAttribute(AttributeKey<T> key, T value)	Sets an attribute to the newly created Span.
ExtendedSpanBuilder	setAttribute(String key, boolean value)	Sets an attribute to the newly created Span.
ExtendedSpanBuilder	setAttribute(String key, double value)	Sets an attribute to the newly created Span.
ExtendedSpanBuilder	setAttribute(String key, long value)	Sets an attribute to the newly created Span.
ExtendedSpanBuilder	setAttribute(String key, String value)	Sets an attribute to the newly created Span.
ExtendedSpanBuilder	setNoParent()	Sets the option to become a root Span for a new trace.
ExtendedSpanBuilder	setParent(Context context)	Sets the parent to use from the specified Context.
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 ExtendedSpanBuilder.startAndCall(SpanCallable) and ExtendedSpanBuilder.startAndRun(SpanRunnable).
private static void	setSpanError(Span span, Throwable exception)	Marks a span as error.
ExtendedSpanBuilder	setSpanKind(SpanKind spanKind)	Sets the SpanKind for the newly created Span.
ExtendedSpanBuilder	setStartTimestamp(long startTimestamp, TimeUnit unit)	Sets an explicit start timestamp for the newly created Span.
<T, E extends Throwable> T	startAndCall(SpanCallable<T,E> spanCallable)	Runs the given SpanCallable inside of the span created by the given SpanBuilder.
<T, E extends Throwable> T	startAndCall(SpanCallable<T,E> spanCallable, BiConsumer<Span, Throwable> handleException)	Runs the given SpanCallable inside of the span created by the given SpanBuilder.
<E extends Throwable> void	startAndRun(SpanRunnable<E> runnable)	Runs the given SpanRunnable inside of the span created by the given SpanBuilder.
<E extends Throwable> void	startAndRun(SpanRunnable<E> runnable, BiConsumer<Span, Throwable> handleException)	Runs the given SpanRunnable inside of the span created by the given SpanBuilder.
Span	startSpan()	Starts a new Span.

Methods inherited from class Object

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

Methods inherited from interface ExtendedSpanBuilder

setAllAttributes, setStartTimestamp

Field Details

spanName

private final String spanName

instrumentationScopeInfo

private final InstrumentationScopeInfo instrumentationScopeInfo

tracerSharedState

private final TracerSharedState tracerSharedState

spanLimits

private final SpanLimits spanLimits

parent

@Nullable
private Context parent

spanKind

private SpanKind spanKind

attributes

@Nullable
private AttributesMap attributes

links

@Nullable
private List<LinkData> links

totalNumberOfLinksAdded

private int totalNumberOfLinksAdded

startEpochNanos

private long startEpochNanos

Constructor Details

SdkSpanBuilder

SdkSpanBuilder(String spanName,
 InstrumentationScopeInfo instrumentationScopeInfo,
 TracerSharedState tracerSharedState,
 SpanLimits spanLimits)

Method Details

setParent

public ExtendedSpanBuilder setParent(Context context)

Description copied from interface: ExtendedSpanBuilder

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 ExtendedSpanBuilder

Specified by:

setParent in interface SpanBuilder

Parameters:

context - the Context.

Returns:

this.

setNoParent

public ExtendedSpanBuilder setNoParent()

Description copied from interface: ExtendedSpanBuilder

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 ExtendedSpanBuilder

Specified by:

setNoParent in interface SpanBuilder

Returns:

this.

setSpanKind

public ExtendedSpanBuilder setSpanKind(SpanKind spanKind)

Description copied from interface: ExtendedSpanBuilder

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 ExtendedSpanBuilder

Specified by:

setSpanKind in interface SpanBuilder

Parameters:

spanKind - the kind of the newly created Span.

Returns:

this.

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(String key,
 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 ExtendedSpanBuilder setAttribute(String key,
 long 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: 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 ExtendedSpanBuilder setAttribute(String key,
 double 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: 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 ExtendedSpanBuilder setAttribute(String key,
 boolean 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: 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,
 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.

setParentFrom

public ExtendedSpanBuilder setParentFrom(ContextPropagators propagators,
 Map<String,String> carrier)

Description copied from interface: ExtendedSpanBuilder

Extract a span context from the given carrier and set it as parent of the span for ExtendedSpanBuilder.startAndCall(SpanCallable) and ExtendedSpanBuilder.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.

Specified by:

setParentFrom in interface ExtendedSpanBuilder

Parameters:

propagators - provide the propagators from OpenTelemetry.getPropagators()

carrier - the string map where to extract the span context from

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

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

startAndCall

public <T, E extends Throwable> T startAndCall(SpanCallable<T,E> spanCallable,
 BiConsumer<Span, Throwable> handleException)
                                        throws E

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

startAndRun

public <E extends Throwable> void startAndRun(SpanRunnable<E> runnable)
                                       throws E

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

startAndRun

public <E extends Throwable> void startAndRun(SpanRunnable<E> runnable,
 BiConsumer<Span, Throwable> handleException)
                                       throws E

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

attributes

private AttributesMap attributes()

isRecording

static boolean isRecording(SamplingDecision decision)

isSampled

static boolean isSampled(SamplingDecision decision)

setSpanError

private static void setSpanError(Span span,
 Throwable exception)

Marks a span as error. This is the default exception handler.

Parameters:

span - the span

exception - the exception that caused the error