Package io.opentelemetry.api.trace

Interface Span.Builder

  • 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 = TracingContextUtils.currentContextWith(span)) {
       TracingContextUtils.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 = TracingContextUtils.currentContextWith(mySpan)) {
       TracingContextUtils.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.

    • Method Detail

      • setParent

        Span.Builder 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.
        Throws:
        NullPointerException - if context is null.

      • setNoParent

        Span.Builder 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

        Span.Builder 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.

        Parameters:
        spanContext - the context of the linked Span.
        Returns:
        this.
        Throws:
        NullPointerException - if spanContext is null.

      • addLink

        Span.Builder 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.

        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.

      • setAttribute

        Span.Builder setAttribute​(String key,
                          @Nonnull
                          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 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.
        Throws:
        NullPointerException - if key is null.

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

        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.
        Throws:
        NullPointerException - if key is null.

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

        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.
        Throws:
        NullPointerException - if key is null.

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

        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.
        Throws:
        NullPointerException - if key is null.

      • setAttribute

        <T> Span.Builder setAttribute​(AttributeKey<T> key,
                              @Nonnull
                              T 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.

        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.
        Throws:
        NullPointerException - if key is null.
        NullPointerException - if value is null.

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

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

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