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.

    • operationName

      public String operationName()

    • traceId

      public String traceId()

    • parentSpanId

      public String parentSpanId()

    • tracingMode

      public TracingMode tracingMode()

    • kind

      public SpanKind kind()