Class SdkSpanBuilder
- All Implemented Interfaces:
ExtendedSpanBuilder
,SpanBuilder
SdkSpanBuilder
is SDK implementation of SpanBuilder
.-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate AttributesMap
private final InstrumentationScopeInfo
private Context
private SpanKind
private final SpanLimits
private final String
private long
private int
private final TracerSharedState
-
Constructor Summary
ConstructorsConstructorDescriptionSdkSpanBuilder
(String spanName, InstrumentationScopeInfo instrumentationScopeInfo, TracerSharedState tracerSharedState, SpanLimits spanLimits) -
Method Summary
Modifier and TypeMethodDescriptionaddLink
(SpanContext spanContext) Adds a link to the newly createdSpan
.addLink
(SpanContext spanContext, Attributes attributes) Adds a link to the newly createdSpan
.private void
private AttributesMap
(package private) static boolean
isRecording
(SamplingDecision decision) (package private) static boolean
isSampled
(SamplingDecision decision) setAttribute
(AttributeKey<T> key, T value) Sets an attribute to the newly createdSpan
.setAttribute
(String key, boolean value) Sets an attribute to the newly createdSpan
.setAttribute
(String key, double value) Sets an attribute to the newly createdSpan
.setAttribute
(String key, long value) Sets an attribute to the newly createdSpan
.setAttribute
(String key, String value) Sets an attribute to the newly createdSpan
.Sets the option to become a rootSpan
for a new trace.Sets the parent to use from the specifiedContext
.setParentFrom
(ContextPropagators propagators, Map<String, String> carrier) Extract a span context from the given carrier and set it as parent of the span forExtendedSpanBuilder.startAndCall(SpanCallable)
andExtendedSpanBuilder.startAndRun(SpanRunnable)
.private static void
setSpanError
(Span span, Throwable exception) Marks a span as error.setSpanKind
(SpanKind spanKind) Sets theSpanKind
for the newly createdSpan
.setStartTimestamp
(long startTimestamp, TimeUnit unit) Sets an explicit start timestamp for the newly createdSpan
.<T,
E extends Throwable>
TstartAndCall
(SpanCallable<T, E> spanCallable) Runs the givenSpanCallable
inside of the span created by the givenSpanBuilder
.<T,
E extends Throwable>
TstartAndCall
(SpanCallable<T, E> spanCallable, BiConsumer<Span, Throwable> handleException) Runs the givenSpanCallable
inside of the span created by the givenSpanBuilder
.<E extends Throwable>
voidstartAndRun
(SpanRunnable<E> runnable) Runs the givenSpanRunnable
inside of the span created by the givenSpanBuilder
.<E extends Throwable>
voidstartAndRun
(SpanRunnable<E> runnable, BiConsumer<Span, Throwable> handleException) Runs the givenSpanRunnable
inside of the span created by the givenSpanBuilder
.Starts a newSpan
.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface io.opentelemetry.api.incubator.trace.ExtendedSpanBuilder
setAllAttributes, setStartTimestamp
-
Field Details
-
spanName
-
instrumentationScopeInfo
-
spanLimits
-
parent
-
spanKind
-
attributes
-
links
-
totalNumberOfLinksAdded
private int totalNumberOfLinksAdded -
startEpochNanos
private long startEpochNanos
-
-
Constructor Details
-
Method Details
-
setParent
Description copied from interface:ExtendedSpanBuilder
Sets the parent to use from the specifiedContext
. If not set, the value ofSpan.current()
atSpanBuilder.startSpan()
time will be used as parent.If no
Span
is available in the specifiedContext
, the resultingSpan
will become a root instance, as ifSpanBuilder.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 interfaceExtendedSpanBuilder
- Specified by:
setParent
in interfaceSpanBuilder
- Parameters:
context
- theContext
.- Returns:
- this.
-
setNoParent
Description copied from interface:ExtendedSpanBuilder
Sets the option to become a rootSpan
for a new trace. If not set, the value ofSpan.current()
atSpanBuilder.startSpan()
time will be used as parent.Observe that any previously set parent will be discarded.
- Specified by:
setNoParent
in interfaceExtendedSpanBuilder
- Specified by:
setNoParent
in interfaceSpanBuilder
- Returns:
- this.
-
setSpanKind
Description copied from interface:ExtendedSpanBuilder
Sets theSpanKind
for the newly createdSpan
. If not called, the implementation will provide a default valueSpanKind.INTERNAL
.- Specified by:
setSpanKind
in interfaceExtendedSpanBuilder
- Specified by:
setSpanKind
in interfaceSpanBuilder
- Parameters:
spanKind
- the kind of the newly createdSpan
.- Returns:
- this.
-
addLink
Description copied from interface:ExtendedSpanBuilder
Adds a link to the newly createdSpan
.Links are used to link
Span
s 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 interfaceExtendedSpanBuilder
- Specified by:
addLink
in interfaceSpanBuilder
- Parameters:
spanContext
- the context of the linkedSpan
.- Returns:
- this.
-
addLink
Description copied from interface:ExtendedSpanBuilder
Adds a link to the newly createdSpan
.Links are used to link
Span
s 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 interfaceExtendedSpanBuilder
- Specified by:
addLink
in interfaceSpanBuilder
- Parameters:
spanContext
- the context of the linkedSpan
.attributes
- the attributes of theLink
.- Returns:
- this.
-
addLink
-
setAttribute
Description copied from interface:ExtendedSpanBuilder
Sets an attribute to the newly createdSpan
. IfSpanBuilder
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 interfaceExtendedSpanBuilder
- Specified by:
setAttribute
in interfaceSpanBuilder
- Parameters:
key
- the key for this attribute.value
- the value for this attribute.- Returns:
- this.
-
setAttribute
Description copied from interface:ExtendedSpanBuilder
Sets an attribute to the newly createdSpan
. IfSpanBuilder
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 interfaceExtendedSpanBuilder
- Specified by:
setAttribute
in interfaceSpanBuilder
- Parameters:
key
- the key for this attribute.value
- the value for this attribute.- Returns:
- this.
-
setAttribute
Description copied from interface:ExtendedSpanBuilder
Sets an attribute to the newly createdSpan
. IfSpanBuilder
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 interfaceExtendedSpanBuilder
- Specified by:
setAttribute
in interfaceSpanBuilder
- Parameters:
key
- the key for this attribute.value
- the value for this attribute.- Returns:
- this.
-
setAttribute
Description copied from interface:ExtendedSpanBuilder
Sets an attribute to the newly createdSpan
. IfSpanBuilder
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 interfaceExtendedSpanBuilder
- Specified by:
setAttribute
in interfaceSpanBuilder
- Parameters:
key
- the key for this attribute.value
- the value for this attribute.- Returns:
- this.
-
setAttribute
Description copied from interface:ExtendedSpanBuilder
Sets an attribute to the newly createdSpan
. IfSpanBuilder
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 interfaceExtendedSpanBuilder
- Specified by:
setAttribute
in interfaceSpanBuilder
- Parameters:
key
- the key for this attribute.value
- the value for this attribute.- Returns:
- this.
-
setStartTimestamp
Description copied from interface:ExtendedSpanBuilder
Sets an explicit start timestamp for the newly createdSpan
.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 interfaceExtendedSpanBuilder
- Specified by:
setStartTimestamp
in interfaceSpanBuilder
- Parameters:
startTimestamp
- the explicit start timestamp from the epoch of the newly createdSpan
.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 forExtendedSpanBuilder.startAndCall(SpanCallable)
andExtendedSpanBuilder.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 interfaceExtendedSpanBuilder
- Parameters:
propagators
- provide the propagators fromOpenTelemetry.getPropagators()
carrier
- the string map where to extract the span context from
-
startSpan
Description copied from interface:SpanBuilder
Starts a newSpan
.Users must manually call
Span.end()
to end thisSpan
.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 interfaceSpanBuilder
- Returns:
- the newly created
Span
.
-
startAndCall
Description copied from interface:ExtendedSpanBuilder
Runs the givenSpanCallable
inside of the span created by the givenSpanBuilder
. The span will be ended at the end of theSpanCallable
.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 interfaceExtendedSpanBuilder
- Type Parameters:
T
- the type of the resultE
- the type of the exception- Parameters:
spanCallable
- theSpanCallable
to call- Returns:
- the result of the
SpanCallable
- Throws:
E
-
startAndCall
public <T,E extends Throwable> T startAndCall(SpanCallable<T, E> spanCallable, BiConsumer<Span, throws EThrowable> handleException) Description copied from interface:ExtendedSpanBuilder
Runs the givenSpanCallable
inside of the span created by the givenSpanBuilder
. The span will be ended at the end of theSpanCallable
.If an exception is thrown by the
SpanCallable
, thehandleException
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 interfaceExtendedSpanBuilder
- Type Parameters:
T
- the type of the resultE
- the type of the exception- Parameters:
spanCallable
- theSpanCallable
to callhandleException
- the consumer to call when an exception is thrown- Returns:
- the result of the
SpanCallable
- Throws:
E
-
startAndRun
Description copied from interface:ExtendedSpanBuilder
Runs the givenSpanRunnable
inside of the span created by the givenSpanBuilder
. The span will be ended at the end of theSpanRunnable
.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 interfaceExtendedSpanBuilder
- Type Parameters:
E
- the type of the exception- Parameters:
runnable
- theSpanRunnable
to run- Throws:
E
-
startAndRun
public <E extends Throwable> void startAndRun(SpanRunnable<E> runnable, BiConsumer<Span, Throwable> handleException) throws EDescription copied from interface:ExtendedSpanBuilder
Runs the givenSpanRunnable
inside of the span created by the givenSpanBuilder
. The span will be ended at the end of theSpanRunnable
.If an exception is thrown by the
SpanRunnable
, thehandleException
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 interfaceExtendedSpanBuilder
- Type Parameters:
E
- the type of the exception- Parameters:
runnable
- theSpanRunnable
to run- Throws:
E
-
attributes
-
isRecording
-
isSampled
-
setSpanError
Marks a span as error. This is the default exception handler.- Parameters:
span
- the spanexception
- the exception that caused the error
-