Package org.bithon.agent.sdk.tracing

Class TraceScopeBuilder

java.lang.Object
org.bithon.agent.sdk.tracing.TraceScopeBuilder
public class TraceScopeBuilder extends Object
Builder for creating trace scopes with fluent API. Use TraceContext.newTrace(String) to create an instance. For example, 

 try (ITraceScope scope = TraceContext.newTrace("operation")
                                      .kind(SpanKind.SERVER)              // MUST give
                                      .parent(traceId, parentSpanId)      // optional
                                      .tracingMode(TracingMode.LOGGING)   // optional, default is TracingMode.TRACING
                                      .attach()) {
          // Update tags if needed
          ISpan span = scope.currentSpan();
          span.tag("key", "value");

          // Business logic here
   }
Author:
frank.chen021@outlook.com
Date:
8/5/25 6:00 pm

  • Field Details

    • LOGGER

      private static final Logger LOGGER

    • LOG_INTERVAL_MS

      private static final long LOG_INTERVAL_MS
      See Also:

    • lastLogTime

      private static long lastLogTime

    • operationName

      private final String operationName

    • traceId

      private String traceId

    • parentSpanId

      private String parentSpanId

    • tracingMode

      private TracingMode tracingMode

    • kind

      private SpanKind kind

  • Constructor Details

    • TraceScopeBuilder

      TraceScopeBuilder(String operationName)

  • Method Details

    • shouldLog

      private static boolean shouldLog()

    • parent

      public TraceScopeBuilder parent(String traceId, String parentSpanId)
      Sets the parent trace context for this trace scope. Use this to continue an existing trace in another thread or context.

      If not set, a new trace(with auto generated trace id and empty parent span id) will be created.

      Parameters:
      traceId - the trace ID of the parent trace
      parentSpanId - the span ID of the parent span
      Returns:
      this builder for method chaining

    • kind

      public TraceScopeBuilder kind(SpanKind kind)

    • tracingMode

      public TraceScopeBuilder tracingMode(TracingMode tracingMode)
      Sets the tracing mode for this trace scope.
      Parameters:
      tracingMode - the tracing mode to use
      Returns:
      this builder for method chaining

    • attach

      public ITraceScope attach()
      Creates a trace scope and attaches it to the current thread.

      The created trace scope has a root span with the operation name and kind specified in the builder. If the kind(SpanKind) is not called, the default kind is SpanKind.INTERNAL.

      Returns:
      an attached ITraceScope ready for use in try-with-resources. Callers MUST ensure to close the scope to avoid resource leaks.
      Throws:
      SdkException - if there's already a trace context attached to the current thread.

    • attachOrReplaceCurrent

      public ITraceScope attachOrReplaceCurrent()
      Creates a trace scope and attaches it to the current thread, temporarily replacing any existing context.

      If parent(String, String) is not configured with a non-empty trace ID and parent span ID, this method returns a no-op scope.

      If a tracing context already exists on the current thread, it will be suspended while the returned scope is active, and restored when the returned scope is closed. The suspended context is not finished by this scope.

      This method is intended for asynchronous task frameworks that need to restore the task's own trace context even when the executor thread already has a context propagated by instrumentation.

      Returns:
      an attached ITraceScope ready for use in try-with-resources. Callers MUST ensure to close the scope to avoid resource leaks and restore the previous context.
      Since:
      1.2.4

    • operationName

      public String operationName()

    • traceId

      public String traceId()

    • parentSpanId

      public String parentSpanId()

    • tracingMode

      public TracingMode tracingMode()

    • kind

      public SpanKind kind()