Span.Builder (opentelemetry-api 0.7.1 API)

Enclosing interface:: Span

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.

Since:: 0.1.0

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Span.Builder`	`addLink(Link link)` Adds a `Link` to the newly created `Span`.
`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`.
`Span.Builder`	`setAttribute(String key, AttributeValue value)` Sets an attribute to the newly created `Span`.
`Span.Builder`	`setAttribute(String key, boolean value)` Sets an attribute to the newly created `Span`.
`Span.Builder`	`setAttribute(String key, double value)` Sets an attribute to the newly created `Span`.
`Span.Builder`	`setAttribute(String key, long value)` Sets an attribute to the newly created `Span`.
`Span.Builder`	`setAttribute(String key, 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`	`setParent(Span parent)` Sets the parent `Span` to use.
`Span.Builder`	`setParent(SpanContext remoteParent)` Sets the parent `SpanContext` to use.
`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`.

- Method Detail
  - setParent
```
Span.Builder setParent(Span parent)
```
    Sets the parent Span to use. If not set, the value of Tracer.getCurrentSpan() at startSpan() time will be used as parent.
    This must be used to create a Span when manual Context propagation is used OR when creating a root Span with a parent with an invalid SpanContext.
    Observe this is the preferred method when the parent is a Span created within the process. Using its SpanContext as parent remains as a valid, albeit inefficient, operation.
    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.
    
    Parameters:
    
    parent - the Span used as parent.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if parent is null.
    
    Since:
    
    0.1.0
    
    See Also:
    
    setNoParent()
  - setParent
```
Span.Builder setParent(SpanContext remoteParent)
```
    Sets the parent SpanContext to use. If not set, the value of Tracer.getCurrentSpan() at startSpan() time will be used as parent.
    Similar to setParent(Span parent) but this must be used to create a Span when the parent is in a different process. This is only intended for use by RPC systems or similar.
    If no SpanContext is available, users must call setNoParent() in order to create a root Span for a new trace.
    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.
    
    Parameters:
    
    remoteParent - the SpanContext used as parent.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if remoteParent is null.
    
    Since:
    
    0.1.0
    
    See Also:
    
    setParent(Span parent), setNoParent()
  - setParent
```
Span.Builder setParent(io.grpc.Context context)
```
    Sets the parent to use from the specified 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.
    
    Parameters:
    
    context - the Context.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if context is null.
    
    Since:
    
    0.7.0
  - setNoParent
```
Span.Builder setNoParent()
```
    Sets the option to become a root 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.
    
    Returns:
    
    this.
    
    Since:
    
    0.1.0
  - addLink
```
Span.Builder addLink(SpanContext spanContext)
```
    Adds a Link to the newly created Span.
    
    Parameters:
    
    spanContext - the context of the linked Span.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if spanContext is null.
    
    Since:
    
    0.1.0
    
    See Also:
    
    addLink(Link)
  - addLink
```
Span.Builder addLink(SpanContext spanContext,
                     Attributes attributes)
```
    Adds a Link to the newly created Span.
    
    Parameters:
    
    spanContext - the context of the linked Span.
    
    attributes - the attributes of the Link.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if spanContext is null.
    
    NullPointerException - if attributes is null.
    
    Since:
    
    0.1.0
    
    See Also:
    
    addLink(Link)
  - addLink
```
Span.Builder addLink(Link link)
```
    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.
    
    Parameters:
    
    link - the Link to be added.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if link is null.
    
    Since:
    
    0.1.0
  - setAttribute
```
Span.Builder setAttribute(String key,
                          @Nullable
                          String value)
```
    Sets an attribute to the newly created 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 attribute will be silently dropped. Note: this behavior could change in the future.
    
    Parameters:
    
    key - the key for this attribute.
    
    value - the value for this attribute.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if key is null.
    
    Since:
    
    0.3.0
  - setAttribute
```
Span.Builder setAttribute(String key,
                          long value)
```
    Sets an attribute to the newly created Span. If Span.Builder previously contained a mapping for the key, the old value is replaced by the specified value.
    
    Parameters:
    
    key - the key for this attribute.
    
    value - the value for this attribute.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if key is null.
    
    Since:
    
    0.3.0
  - setAttribute
```
Span.Builder setAttribute(String key,
                          double value)
```
    Sets an attribute to the newly created Span. If Span.Builder previously contained a mapping for the key, the old value is replaced by the specified value.
    
    Parameters:
    
    key - the key for this attribute.
    
    value - the value for this attribute.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if key is null.
    
    Since:
    
    0.3.0
  - setAttribute
```
Span.Builder setAttribute(String key,
                          boolean value)
```
    Sets an attribute to the newly created Span. If Span.Builder previously contained a mapping for the key, the old value is replaced by the specified value.
    
    Parameters:
    
    key - the key for this attribute.
    
    value - the value for this attribute.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if key is null.
    
    Since:
    
    0.3.0
  - setAttribute
```
Span.Builder setAttribute(String key,
                          AttributeValue value)
```
    Sets an attribute to the newly created Span. If Span.Builder previously contained a mapping for the key, the old value is replaced by the specified value.
    
    Parameters:
    
    key - the key for this attribute.
    
    value - the value for this attribute.
    
    Returns:
    
    this.
    
    Throws:
    
    NullPointerException - if key is null.
    
    NullPointerException - if value is null.
    
    Since:
    
    0.3.0
  - setSpanKind
```
Span.Builder setSpanKind(Span.Kind spanKind)
```
    Sets the Span.Kind for the newly created Span. If not called, the implementation will provide a default value Span.Kind.INTERNAL.
    
    Parameters:
    
    spanKind - the kind of the newly created Span.
    
    Returns:
    
    this.
    
    Since:
    
    0.1.0
  - setStartTimestamp
```
Span.Builder setStartTimestamp(long 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 startSpan() time, which should be the default case.
    Important this is NOT equivalent with System.nanoTime().
    
    Parameters:
    
    startTimestamp - the explicit start timestamp of the newly created Span in nanos since epoch.
    
    Returns:
    
    this.
    
    Since:
    
    0.1.0
  - startSpan
```
Span startSpan()
```
    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 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.
     }
   }
 }
 
```
    Returns:
    
    the newly created Span.
    
    Since:
    
    0.1.0

Interface Span.Builder

Method Summary

Method Detail

setParent

setParent

setParent

setNoParent

addLink

addLink

addLink

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setSpanKind

setStartTimestamp

startSpan