feat: Add telemetry and metrics recording capabilities

The key changes include:

1.  **New `Instrumentation.java` class:** This class provides a unified context manager for instrumenting agent invocations and tool executions. It uses OpenTelemetry to create trace spans, record exceptions, and manage the scope of telemetry contexts. It includes inner classes `AgentInvocation` and `ToolExecution`, both implementing `AutoCloseable` to automatically handle the lifecycle of spans and metric recording.

2.  **New `Metrics.java` class:** This utility class is responsible for defining and recording various OpenTelemetry metrics (histograms) related to ADK components. These metrics cover:
    *   Agent invocation duration, request size, response size, and workflow steps.
    *   Tool execution duration, request size, and response size.
    The class uses `GlobalOpenTelemetry` to get a `Meter` and defines static histogram instances. It includes methods to record values for these metrics, often including attributes like agent name, tool name, and error type.

3.  **New Unit Tests:**
    *   `InstrumentationTest.java`: Contains unit tests for the `Instrumentation` class, verifying that spans are created correctly, contexts are managed, and metrics are recorded for both successful and error scenarios during agent invocations and tool executions. It uses `OpenTelemetryRule` for testing.
    *   `MetricsTest.java`: Contains unit tests for the `Metrics` class, ensuring that the various static methods correctly record histogram data with the expected values and attributes. It also uses `OpenTelemetryRule`.

PiperOrigin-RevId: 917904663

Author: google-genai-bot

core/src/main/java/com/google/adk/telemetry/Instrumentation.java

@@ -0,0 +1,185 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.adk.telemetry;
+
+import com.google.adk.agents.BaseAgent;
+import com.google.adk.agents.InvocationContext;
+import com.google.adk.events.Event;
+import com.google.adk.tools.BaseTool;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.context.Scope;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CopyOnWriteArrayList;
+import org.jspecify.annotations.Nullable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/** Unified context manager utility class for agent and tool execution telemetry in ADK. */
+public final class Instrumentation {
+
+  private static final Logger logger = LoggerFactory.getLogger(Instrumentation.class);
+
+  private Instrumentation() {}
+
+  /** Stores all telemetry related state. */
+  public static final class TelemetryContext {
+    private final Context otelContext;
+    private @Nullable Event functionResponseEvent;
+
+    public TelemetryContext(Context otelContext) {
+      this.otelContext = otelContext;
+    }
+
+    public Context otelContext() {
+      return otelContext;
+    }
+
+    public @Nullable Event functionResponseEvent() {
+      return functionResponseEvent;
+    }
+
+    public void setFunctionResponseEvent(@Nullable Event functionResponseEvent) {
+      this.functionResponseEvent = functionResponseEvent;
+    }
+  }
+
+  /** AutoCloseable telemetry tracking scope for agent invocations. */
+  public static final class AgentInvocation implements AutoCloseable {
+    private final long startTimeNanos;
+    private final BaseAgent agent;
+    private final InvocationContext ctx;
+    private final Span span;
+    private final Scope scope;
+    private final TelemetryContext telemetryContext;
+    private @Nullable Throwable caughtError;
+    private final List<Event> events = new CopyOnWriteArrayList<>();
+
+    @SuppressWarnings("MustBeClosedChecker")
+    public AgentInvocation(InvocationContext ctx, BaseAgent agent) {
+      this.startTimeNanos = System.nanoTime();
+      this.agent = agent;
+      this.ctx = ctx;
+      this.span = Tracing.getTracer().spanBuilder("invoke_agent " + agent.name()).startSpan();
+      Tracing.traceAgentInvocation(span, agent.name(), agent.description(), ctx);
+      this.scope = span.makeCurrent();
+      this.telemetryContext = new TelemetryContext(Context.current());
+    }
+
+    public InvocationContext getCtx() {
+      return ctx;
+    }
+
+    public void addEvent(Event event) {
+      events.add(event);
+    }
+
+    public TelemetryContext context() {
+      return telemetryContext;
+    }
+
+    public void setError(Throwable caughtError) {
+      this.caughtError = caughtError;
+      span.recordException(caughtError);
+      span.setStatus(io.opentelemetry.api.trace.StatusCode.ERROR, caughtError.getMessage());
+    }
+
+    @Override
+    public void close() {
+      scope.close();
+      span.end();
+      double elapsedMs = (System.nanoTime() - startTimeNanos) / 1e6;
+      try {
+        Metrics.recordAgentInvocationDuration(agent.name(), elapsedMs, caughtError);
+        Metrics.recordAgentRequestSize(agent.name(), ctx.userContent().orElse(null));
+        Metrics.recordAgentResponseSize(agent.name(), events);
+        Metrics.recordAgentWorkflowSteps(agent.name(), events);
+      } catch (RuntimeException e) {
+        logger.error("Failed to record agent metrics for agent {}", agent.name(), e);
+      }
+    }
+  }
+
+  /** AutoCloseable telemetry tracking scope for tool executions. */
+  public static final class ToolExecution implements AutoCloseable {
+    private final long startTimeNanos;
+    private final BaseTool tool;
+    private final BaseAgent agent;
+    private final Map<String, Object> functionArgs;
+    private final Span span;
+    private final Scope scope;
+    private final TelemetryContext telemetryContext;
+    private @Nullable Throwable caughtError;
+
+    @SuppressWarnings("MustBeClosedChecker")
+    public ToolExecution(BaseTool tool, BaseAgent agent, Map<String, Object> functionArgs) {
+      this.startTimeNanos = System.nanoTime();
+      this.tool = tool;
+      this.agent = agent;
+      this.functionArgs = functionArgs;
+      this.span = Tracing.getTracer().spanBuilder("execute_tool " + tool.name()).startSpan();
+      this.scope = span.makeCurrent();
+      this.telemetryContext = new TelemetryContext(Context.current());
+    }
+
+    public TelemetryContext context() {
+      return telemetryContext;
+    }
+
+    public void setError(Throwable caughtError) {
+      this.caughtError = caughtError;
+      span.recordException(caughtError);
+      span.setStatus(io.opentelemetry.api.trace.StatusCode.ERROR, caughtError.getMessage());
+    }
+
+    @Override
+    public void close() {
+      scope.close();
+      Event responseEvent = caughtError == null ? telemetryContext.functionResponseEvent() : null;
+      Tracing.traceToolExecution(
+          span,
+          tool.name(),
+          tool.description(),
+          tool.getClass().getSimpleName(),
+          functionArgs,
+          responseEvent,
+          caughtError instanceof Exception ? (Exception) caughtError : null);
+      span.end();
+
+      double elapsedMs = (System.nanoTime() - startTimeNanos) / 1e6;
+      try {
+        Metrics.recordToolExecutionDuration(tool.name(), agent.name(), elapsedMs, caughtError);
+        Metrics.recordToolRequestSize(tool.name(), agent.name(), functionArgs);
+        Metrics.recordToolResponseSize(tool.name(), agent.name(), responseEvent);
+      } catch (RuntimeException e) {
+        logger.error("Failed to record tool execution duration for tool {}", tool.name(), e);
+      }
+    }
+  }
+
+  /** Creates an AgentInvocation context to record agent invocation telemetry. */
+  public static AgentInvocation recordAgentInvocation(InvocationContext ctx, BaseAgent agent) {
+    return new AgentInvocation(ctx, agent);
+  }
+
+  /** Creates a ToolExecution context to record tool execution telemetry. */
+  public static ToolExecution recordToolExecution(
+      BaseTool tool, BaseAgent agent, Map<String, Object> functionArgs) {
+    return new ToolExecution(tool, agent, functionArgs);
+  }
+}