public static interface Span.Builder
Span.Builder
is used to construct Span
instances which define arbitrary scopes of
code that are sampled for distributed tracing as a single atomic unit.
This is a simple example where all the work is being done within a single scope and a single thread and the Context is automatically propagated:
class MyClass {
private static final Tracer tracer = OpenTelemetry.getTracer();
void doWork {
// Create a Span as a child of the current Span.
Span span = tracer.spanBuilder("MyChildSpan").startSpan();
try (Scope ss = tracer.withSpan(span)) {
tracer.getCurrentSpan().addEvent("my event");
doSomeWork(); // Here the new span is in the current Context, so it can be used
// implicitly anywhere down the stack.
} finally {
span.end();
}
}
}
There might be cases where you do not perform all the work inside one static scope and the Context is automatically propagated:
class MyRpcServerInterceptorListener implements RpcServerInterceptor.Listener {
private static final Tracer tracer = OpenTelemetry.getTracer();
private Span mySpan;
public MyRpcInterceptor() {}
public void onRequest(String rpcName, Metadata metadata) {
// Create a Span as a child of the remote Span.
mySpan = tracer.spanBuilder(rpcName)
.setParent(getTraceContextFromMetadata(metadata)).startSpan();
}
public void onExecuteHandler(ServerCallHandler serverCallHandler) {
try (Scope ws = tracer.withSpan(mySpan)) {
tracer.getCurrentSpan().addEvent("Start rpc execution.");
serverCallHandler.run(); // Here the new span is in the current Context, so it can be
// used implicitly anywhere down the stack.
}
}
// Called when the RPC is canceled and guaranteed onComplete will not be called.
public void onCancel() {
// IMPORTANT: DO NOT forget to ended the Span here as the work is done.
mySpan.setStatus(Status.CANCELLED);
mySpan.end();
}
// Called when the RPC is done and guaranteed onCancel will not be called.
public void onComplete(RpcStatus rpcStatus) {
// IMPORTANT: DO NOT forget to ended the Span here as the work is done.
mySpan.setStatus(rpcStatusToCanonicalTraceStatus(status);
mySpan.end();
}
}
This is a simple example where all the work is being done within a single scope and the Context is manually propagated:
class MyClass {
private static final Tracer tracer = OpenTelemetry.getTracer();
void DoWork(Span parent) {
Span childSpan = tracer.spanBuilder("MyChildSpan")
.setParent(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.
}
}
}
If your Java version is less than Java SE 7, see startSpan()
for usage
examples.
Modifier and Type | Method and Description |
---|---|
Span.Builder |
addLink(SpanContext spanContext)
Adds a link to the newly created
Span . |
Span.Builder |
addLink(SpanContext spanContext,
Attributes attributes)
Adds a link to the newly created
Span . |
<T> Span.Builder |
setAttribute(AttributeKey<T> key,
T value)
Sets an attribute to the newly created
Span . |
Span.Builder |
setAttribute(java.lang.String key,
boolean value)
Sets an attribute to the newly created
Span . |
Span.Builder |
setAttribute(java.lang.String key,
double value)
Sets an attribute to the newly created
Span . |
Span.Builder |
setAttribute(java.lang.String key,
long value)
Sets an attribute to the newly created
Span . |
Span.Builder |
setAttribute(java.lang.String key,
java.lang.String value)
Sets an attribute to the newly created
Span . |
Span.Builder |
setNoParent()
Sets the option to become a root
Span for a new trace. |
Span.Builder |
setParent(io.grpc.Context context)
Sets the parent to use from the specified
Context . |
Span.Builder |
setSpanKind(Span.Kind spanKind)
Sets the
Span.Kind for the newly created Span . |
Span.Builder |
setStartTimestamp(long startTimestamp)
Sets an explicit start timestamp for the newly created
Span . |
Span |
startSpan()
Starts a new
Span . |
Span.Builder setParent(io.grpc.Context context)
Context
. If not set, the value of Tracer.getCurrentSpan()
at 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 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 setNoParent()
will be discarded.
context
- the Context
.java.lang.NullPointerException
- if context
is null
.Span.Builder setNoParent()
Span
for a new trace. If not set, the value of
Tracer.getCurrentSpan()
at startSpan()
time will be used as parent.
Observe that any previously set parent will be discarded.
Span.Builder addLink(SpanContext spanContext)
Span
.
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.
spanContext
- the context of the linked Span
.java.lang.NullPointerException
- if spanContext
is null
.Span.Builder addLink(SpanContext spanContext, Attributes attributes)
Span
.
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.
spanContext
- the context of the linked Span
.attributes
- the attributes of the Link
.java.lang.NullPointerException
- if spanContext
is null
.java.lang.NullPointerException
- if attributes
is null
.Span.Builder setAttribute(java.lang.String key, @Nonnull java.lang.String value)
Span
. If Span.Builder
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 setAttribute(AttributeKey, Object)
, and
pre-allocate your keys, if possible.
key
- the key for this attribute.value
- the value for this attribute.java.lang.NullPointerException
- if key
is null
.Span.Builder setAttribute(java.lang.String key, long value)
Span
. If Span.Builder
previously
contained a mapping for the key, the old value is replaced by the specified value.
Note: It is strongly recommended to use setAttribute(AttributeKey, Object)
, and
pre-allocate your keys, if possible.
key
- the key for this attribute.value
- the value for this attribute.java.lang.NullPointerException
- if key
is null
.Span.Builder setAttribute(java.lang.String key, double value)
Span
. If Span.Builder
previously
contained a mapping for the key, the old value is replaced by the specified value.
Note: It is strongly recommended to use setAttribute(AttributeKey, Object)
, and
pre-allocate your keys, if possible.
key
- the key for this attribute.value
- the value for this attribute.java.lang.NullPointerException
- if key
is null
.Span.Builder setAttribute(java.lang.String key, boolean value)
Span
. If Span.Builder
previously
contained a mapping for the key, the old value is replaced by the specified value.
Note: It is strongly recommended to use setAttribute(AttributeKey, Object)
, and
pre-allocate your keys, if possible.
key
- the key for this attribute.value
- the value for this attribute.java.lang.NullPointerException
- if key
is null
.<T> Span.Builder setAttribute(AttributeKey<T> key, @Nonnull T value)
Span
. If Span.Builder
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.
key
- the key for this attribute.value
- the value for this attribute.java.lang.NullPointerException
- if key
is null
.java.lang.NullPointerException
- if value
is null
.Span.Builder setSpanKind(Span.Kind spanKind)
Span.Kind
for the newly created Span
. If not called, the
implementation will provide a default value Span.Kind.INTERNAL
.spanKind
- the kind of the newly created Span
.Span.Builder setStartTimestamp(long startTimestamp)
Span
.
Use this method to specify an explicit start timestamp. If not called, the implementation
will use the timestamp value at startSpan()
time, which should be the default case.
Important this is NOT equivalent with System.nanoTime().
startTimestamp
- the explicit start timestamp of the newly created Span
in nanos
since epoch.Span startSpan()
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 Span.Builder
instance and as the
last method called. After this method is called calling any method is undefined behavior.
Example of usage:
class MyClass {
private static final Tracer tracer = OpenTelemetry.getTracer();
void DoWork(Span parent) {
Span childSpan = tracer.spanBuilder("MyChildSpan")
.setParent(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.
}
}
}
Span
.