Class Tracing

java.lang.Object
com.google.adk.telemetry.Tracing
public class Tracing extends Object
Utility class for capturing and reporting telemetry data within the ADK. This class provides methods to trace various aspects of the agent's execution, including tool calls, tool responses, LLM interactions, and data handling. It leverages OpenTelemetry for tracing and logging for detailed information. These traces can then be exported through the ADK Dev Server UI.

  • Method Details

    • setTracerForTesting

      public static void setTracerForTesting(io.opentelemetry.api.trace.Tracer tracer)
      Sets the OpenTelemetry instance to be used for tracing. This is for testing purposes only.

    • traceAgentInvocation

      public static void traceAgentInvocation(io.opentelemetry.api.trace.Span span, String agentName, String agentDescription, InvocationContext invocationContext)
      Sets span attributes immediately available on agent invocation according to OTEL semconv version 1.37.
      Parameters:
      span - Span on which attributes are set.
      agentName - Agent name from which attributes are gathered.
      agentDescription - Agent description from which attributes are gathered.
      invocationContext - InvocationContext from which attributes are gathered.

    • traceToolCall

      public static void traceToolCall(String toolName, String toolDescription, String toolType, Map<String,Object> args)
      Traces tool call arguments.
      Parameters:
      args - The arguments to the tool call.

    • traceToolResponse

      public static void traceToolResponse(String eventId, Event functionResponseEvent)
      Traces tool response event.
      Parameters:
      eventId - The ID of the event.
      functionResponseEvent - The function response event.

    • traceCallLlm

      public static void traceCallLlm(InvocationContext invocationContext, String eventId, LlmRequest llmRequest, LlmResponse llmResponse)
      Traces a call to the LLM.
      Parameters:
      invocationContext - The invocation context.
      eventId - The ID of the event associated with this LLM call/response.
      llmRequest - The LLM request object.
      llmResponse - The LLM response object.

    • traceSendData

      public static void traceSendData(InvocationContext invocationContext, String eventId, List<com.google.genai.types.Content> data)
      Traces the sending of data (history or new content) to the agent/model.
      Parameters:
      invocationContext - The invocation context.
      eventId - The ID of the event, if applicable.
      data - A list of content objects being sent.

    • getTracer

      public static io.opentelemetry.api.trace.Tracer getTracer()
      Gets the tracer.
      Returns:
      The tracer.

    • traceFlowable

      public static <T> io.reactivex.rxjava3.core.Flowable<T> traceFlowable(io.opentelemetry.context.Context spanContext, io.opentelemetry.api.trace.Span span, Supplier<io.reactivex.rxjava3.core.Flowable<T>> flowableSupplier)
      Executes a Flowable with an OpenTelemetry Scope active for its entire lifecycle.

      This helper manages the OpenTelemetry Scope lifecycle for RxJava Flowables to ensure proper context propagation across async boundaries. The scope remains active from when the Flowable is returned through all operators until stream completion (onComplete, onError, or cancel).

      Why not try-with-resources? RxJava Flowables execute lazily - operators run at subscription time, not at chain construction time. Using try-with-resources would close the scope before the Flowable subscribes, causing Context.current() to return ROOT in nested operations and breaking parent-child span relationships (fragmenting traces).

      The scope is properly closed via doFinally when the stream terminates, ensuring no resource leaks regardless of completion mode (success, error, or cancellation).

      Type Parameters:
      T - The type of items emitted by the Flowable
      Parameters:
      spanContext - The context containing the span to activate
      span - The span to end when the stream completes
      flowableSupplier - Supplier that creates the Flowable to execute with active scope
      Returns:
      Flowable with OpenTelemetry scope lifecycle management

    • trace

      public static <T> Tracing.TracerProvider<T> trace(String spanName)
      Returns a transformer that traces the execution of an RxJava stream.
      Type Parameters:
      T - The type of the stream.
      Parameters:
      spanName - The name of the span to create.
      Returns:
      A TracerProvider that can be used with .compose().

    • trace

      public static <T> Tracing.TracerProvider<T> trace(String spanName, io.opentelemetry.context.Context parentContext)
      Returns a transformer that traces the execution of an RxJava stream with an explicit parent context.
      Type Parameters:
      T - The type of the stream.
      Parameters:
      spanName - The name of the span to create.
      parentContext - The explicit parent context for the span.
      Returns:
      A TracerProvider that can be used with .compose().

    • traceAgent

      public static <T> Tracing.TracerProvider<T> traceAgent(String spanName, String agentName, String agentDescription, InvocationContext invocationContext)
      Returns a transformer that traces an agent invocation.
      Type Parameters:
      T - The type of the stream.
      Parameters:
      spanName - The name of the span to create.
      agentName - The name of the agent.
      agentDescription - The description of the agent.
      invocationContext - The invocation context.
      Returns:
      A TracerProvider configured for agent invocation.