Package com.couchbase.client.core.cnc

Interface RequestSpan

All Known Implementing Classes:
NoopRequestSpan, ThresholdRequestSpan
@Volatile public interface RequestSpan
Wrapper interface for all spans flowing through the SDK.

Note that you'll most likely consume this interface through actual implementations from the tracer module that is used for your application. You will not need to worry about this with the default threshold request tracer, but if you are using OpenTracing or OpenTelemetry, look in their respective modules for implementations of this class.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    RequestSpan.StatusCode
    Provides an abstraction over underlying tracing status codes.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    attribute(String key, boolean value)
    Sets a high-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.
    void
    attribute(String key, long value)
    Sets a high-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.
    void
    attribute(String key, String value)
    Sets a high-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.
    void
    end()
    Completes this span.
    void
    event(String name, Instant timestamp)
    Sets an event on the span, which is translated to the corresponding implementation specific event.
    default void
    lowCardinalityAttribute(String key, boolean value)
    Sets a low-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.
    default void
    lowCardinalityAttribute(String key, long value)
    Sets a low-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.
    default void
    lowCardinalityAttribute(String key, String value)
    Sets a low-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.
    default void
    recordException(Throwable err)
    Records that an exception happened on the span.
    void
    requestContext(RequestContext requestContext)
    Allows to set a request context to the request span.
    void
    status(RequestSpan.StatusCode status)
    Sets the status of the span, which is by default UNSET.

  • Method Details

    • attribute

      void attribute(String key, String value)
      Sets a high-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.

      Note that, depending on the implementation, attributes might be ignored.

      Parameters:
      key - the key of the attribute.
      value - the value of the attribute.

    • attribute

      void attribute(String key, boolean value)
      Sets a high-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.

      Note that, depending on the implementation, attributes might be ignored.

      Parameters:
      key - the key of the attribute.
      value - the value of the attribute.

    • attribute

      void attribute(String key, long value)
      Sets a high-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.

      Note that, depending on the implementation, attributes might be ignored.

      Parameters:
      key - the key of the attribute.
      value - the value of the attribute.

    • lowCardinalityAttribute

      @Internal default void lowCardinalityAttribute(String key, String value)
      Sets a low-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.

      Note that, depending on the implementation, attributes might be ignored.

      Parameters:
      key - the key of the attribute.
      value - the value of the attribute.

    • lowCardinalityAttribute

      @Internal default void lowCardinalityAttribute(String key, boolean value)
      Sets a low-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.

      Note that, depending on the implementation, attributes might be ignored.

      Parameters:
      key - the key of the attribute.
      value - the value of the attribute.

    • lowCardinalityAttribute

      @Internal default void lowCardinalityAttribute(String key, long value)
      Sets a low-cardinality attribute on the span, which is translated to the corresponding implementation specific tag.

      Note that, depending on the implementation, attributes might be ignored.

      Parameters:
      key - the key of the attribute.
      value - the value of the attribute.

    • event

      void event(String name, Instant timestamp)
      Sets an event on the span, which is translated to the corresponding implementation specific event.

      Note that, depending on the implementation, events might be ignored.

      Parameters:
      name - the name of the event
      timestamp - the timestamp when it happened.

    • status

      void status(RequestSpan.StatusCode status)
      Sets the status of the span, which is by default UNSET.

      Note that, depending on the implementation, this might be a no-op.

      Parameters:
      status - the span's new status.

    • recordException

      @Volatile default void recordException(Throwable err)
      Records that an exception happened on the span. What this does is dependent on the underlying telemetry implementation - in some implementations it is a no-op.

      The span still needs to have `span.end()` called. And the application may want to set the status to StatusCode.ERROR. Neither is done automatically, since it's possible for a span to have an exception but then recover.

      Parameters:
      err - the exception to record.

    • end

      void end()
      Completes this span.

    • requestContext

      @Internal void requestContext(RequestContext requestContext)
      Allows to set a request context to the request span.
      Parameters:
      requestContext - the request context, if present.