Package io.opentelemetry.api.trace

Interface SpanBuilder

public interface SpanBuilder
SpanBuilder 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 final Tracer tracer;

   MyClass(OpenTelemetry openTelemetry) {
     tracer = openTelemetry.getTracer("com.anyco.rpc");
   }

   void doWork() {
     // Create a Span as a child of the current Span.
     Span span = tracer.spanBuilder("MyChildSpan").startSpan();
     try (Scope ss = span.makeCurrent()) {
       span.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 final Tracer tracer;
   private Span mySpan;

   public MyRpcInterceptor(OpenTelemetry openTelemetry) {
     tracer = openTelemetry.getTracer("com.example.rpc");
   }

   public void onRequest(String rpcName, Metadata metadata) {
     // Create a Span as a child of the remote Span.
     mySpan = tracer.spanBuilder(rpcName)
         .setParent(extractContextFromMetadata(metadata)).startSpan();
   }

   public void onExecuteHandler(ServerCallHandler serverCallHandler) {
     try (Scope ws = mySpan.makeCurrent()) {
       Span.current().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(StatusCode.ERROR);
     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 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.
     }
   }
 }

see startSpan() for usage examples.

  • Method Details

    • setParent

      SpanBuilder setParent(io.opentelemetry.context.Context context)
      Sets the parent to use from the specified Context. If not set, the value of Span.current() 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.

    • setNoParent

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

      Observe that any previously set parent will be discarded.

      Returns:
      this.

    • addLink

      SpanBuilder 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.

      Parameters:
      spanContext - the context of the linked Span.
      Returns:
      this.

    • addLink

      SpanBuilder 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.

      Parameters:
      spanContext - the context of the linked Span.
      attributes - the attributes of the Link.
      Returns:
      this.

    • setAttribute

      SpanBuilder 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 setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

      Parameters:
      key - the key for this attribute.
      value - the value for this attribute.
      Returns:
      this.

    • setAttribute

      SpanBuilder 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 setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

      Parameters:
      key - the key for this attribute.
      value - the value for this attribute.
      Returns:
      this.

    • setAttribute

      SpanBuilder 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 setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

      Parameters:
      key - the key for this attribute.
      value - the value for this attribute.
      Returns:
      this.

    • setAttribute

      SpanBuilder 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 setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

      Parameters:
      key - the key for this attribute.
      value - the value for this attribute.
      Returns:
      this.

    • setAttribute

      <T> SpanBuilder 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.

      Parameters:
      key - the key for this attribute.
      value - the value for this attribute.
      Returns:
      this.

    • setAllAttributes

      default SpanBuilder 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.
      Parameters:
      attributes - the attributes
      Returns:
      this.
      Since:
      1.2.0

    • setSpanKind

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

    • setStartTimestamp

      SpanBuilder 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 startSpan() time, which should be the default case.

      Important this is NOT equivalent with System.nanoTime().

      Parameters:
      startTimestamp - the explicit start timestamp from the epoch of the newly created Span.
      unit - the unit of the timestamp.
      Returns:
      this.

    • setStartTimestamp

      default SpanBuilder 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 startSpan() time, which should be the default case.

      Important this is NOT equivalent with System.nanoTime().

      Parameters:
      startTimestamp - the explicit start timestamp from the epoch of the newly created Span.
      Returns:
      this.

    • 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 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.
     }
   }
 }
      Returns:
      the newly created Span.