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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `Tracing.ContextTransformer<T>`
  A transformer that re-activates a given context for the duration of the stream's subscription.
  `static final class`
  `Tracing.TracerProvider<T>`
  A transformer that manages an OpenTelemetry span and scope for RxJava streams.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static io.opentelemetry.api.trace.Tracer`
  `getTracer()`
  Gets the tracer.
  `static void`
  `setTracerForTesting(io.opentelemetry.api.trace.Tracer tracer)`
  Sets the OpenTelemetry instance to be used for tracing.
  `static <T> Tracing.TracerProvider<T>`
  `trace(String spanName)`
  Returns a transformer that traces the execution of an RxJava stream.
  `static <T> Tracing.TracerProvider<T>`
  `traceAgent(String spanName, String agentName, String agentDescription, InvocationContext invocationContext)`
  Returns a transformer that traces an agent invocation.
  `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.
  `static void`
  `traceCallLlm(io.opentelemetry.api.trace.Span span, InvocationContext invocationContext, String eventId, LlmRequest llmRequest, LlmResponse llmResponse, @Nullable Exception error)`
  Traces a call to the LLM.
  `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.
  `static void`
  `traceMergedToolCalls(io.opentelemetry.api.trace.Span span, String responseEventId, Event functionResponseEvent)`
  Traces merged tool call events.
  `static void`
  `traceSendData(io.opentelemetry.api.trace.Span span, InvocationContext invocationContext, String eventId, List<com.google.genai.types.Content> data)`
  Traces the sending of data (history or new content) to the agent/model.
  `static void`
  `traceToolExecution(io.opentelemetry.api.trace.Span span, String toolName, String toolDescription, String toolType, Map<String,Object> args, @Nullable Event functionResponseEvent, @Nullable Exception error)`
  Traces a tool execution, including its arguments, response, and any potential error.
  `static <T> Tracing.ContextTransformer<T>`
  `withContext(io.opentelemetry.context.Context context)`
  Returns a transformer that re-activates a given context for the duration of the stream's subscription.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

  - ### traceToolExecution

    public static void traceToolExecution(io.opentelemetry.api.trace.Span span, String toolName, String toolDescription, String toolType, Map<String,Object> args, @Nullable Event functionResponseEvent, @Nullable Exception error)
    Traces a tool execution, including its arguments, response, and any potential error.
    Parameters:
      `span` - The span representing the tool execution.
      `toolName` - The name of the tool.
      `toolDescription` - The tool's description.
      `toolType` - The tool's type (e.g., "FunctionTool").
      `args` - The arguments passed to the tool.
      `functionResponseEvent` - The event containing the tool's response, if successful.
      `error` - The exception thrown during execution, if any.

  - ### traceCallLlm

    public static void traceCallLlm(io.opentelemetry.api.trace.Span span, InvocationContext invocationContext, String eventId, LlmRequest llmRequest, LlmResponse llmResponse, @Nullable Exception error)
    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(io.opentelemetry.api.trace.Span span, 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.

  - ### traceMergedToolCalls

    public static void traceMergedToolCalls(io.opentelemetry.api.trace.Span span, String responseEventId, Event functionResponseEvent)
    Traces merged tool call events.

    Calling this function is not needed for telemetry purposes. This is provided for preventing /debug/trace requests (typically sent by web UI).

    Parameters:
      `responseEventId` - The ID of the response event.
      `functionResponseEvent` - The merged response event.

  - ### 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().

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

  - ### withContext

    public static <T> Tracing.ContextTransformer<T> withContext(io.opentelemetry.context.Context context)
    Returns a transformer that re-activates a given context for the duration of the stream's subscription.
    Type Parameters:
      `T` - The type of the stream.
    Parameters:
      `context` - The context to re-activate.
    Returns:
      A transformer that re-activates the context.