OpenInference Google ADK Instrumentation

Common errors

• No traces appearing in my observability backend/console.

  cause This usually indicates an issue with the OpenTelemetry setup or the Google ADK configuration. Common causes include a missing `GOOGLE_API_KEY`, the `tracer_provider` not being correctly configured or passed to the instrumentor, or the spans not being exported due to an incorrectly configured OTLP exporter endpoint.
  fix Verify that `GOOGLE_API_KEY` is set correctly. Ensure you have called `GoogleADKInstrumentor().instrument(tracer_provider=tracer_provider)` and that `tracer_provider` is configured with an active `SpanProcessor` (e.g., `OTLPSpanExporter`) and `trace.set_tracer_provider(tracer_provider)` has been called. Also, confirm your OTLP endpoint is reachable and correct.

• ModuleNotFoundError: No module named 'google.adk'

  cause The `openinference-instrumentation-google-adk` package instruments the `google-adk` library. While `google-adk` is listed as an optional dependency in some metadata, it is effectively required for the instrumentation to be useful. This error means `google-adk` itself is not installed.
  fix Install the `google-adk` package: `pip install google-adk`.

• RuntimeError: Cannot set tracer provider multiple times.

  cause This error occurs if `opentelemetry.trace.set_tracer_provider()` is called more than once in the application lifecycle. This can happen in complex applications or test environments where instrumentation is repeatedly initialized.
  fix Ensure `trace.set_tracer_provider()` is called only once, typically at the application's entry point. If using an external framework that also sets a global tracer, you might need to avoid setting it globally or configure instrumentation at a lower level with a local `tracer_provider` as shown in some deployment examples (e.g., for Agent Engine [17]).

Warnings

• gotcha Google ADK itself may use 'Pre-GA' features. The instrumentation's behavior might be subject to change or have limited support when interacting with these features. Always refer to Google's official ADK documentation for stability status. [5]
  Fix: Stay updated with Google ADK and OpenInference releases. Consult the respective project documentation for any breaking changes related to Pre-GA features.
• gotcha When deploying Google ADK agents to Vertex AI Agent Engine, the instrumentation must be configured within the remote agent module, not in the main application code. Additionally, it might be necessary to set `set_global_tracer_provider=False` when registering the tracer to avoid conflicts with the Agent Engine's own global provider. [11, 17]
  Fix: Ensure instrumentation setup (e.g., `GoogleADKInstrumentor().instrument(...)`) is inside the agent module. If conflicts arise, pass `set_global_tracer_provider=False` to your OpenTelemetry provider registration function.
• gotcha The instrumentation relies on the `GOOGLE_API_KEY` environment variable being correctly set for authentication with Gemini models via Google ADK. Failure to set this will prevent the underlying ADK agent from functioning and thus no traces will be generated. [3, 6, 11, 16, 17]
  Fix: Set `GOOGLE_API_KEY` in your environment (e.g., `export GOOGLE_API_KEY="your_key_here"`) or pass it directly in your application's configuration where `google-adk` is initialized.

Install

• pip install openinference-instrumentation-google-adk google-adk opentelemetry-sdk opentelemetry-exporter-otlp Recommended Installation

Imports

• GoogleADKInstrumentor

  from openinference.instrumentation.google_adk import GoogleADKInstrumentor

Quickstart

This quickstart demonstrates how to set up OpenTelemetry tracing for a Google ADK agent using `openinference-instrumentation-google-adk`. It configures a `TracerProvider` (showing both console and OTLP export options), initializes the `GoogleADKInstrumentor`, and then runs a basic ADK agent that uses a tool. Ensure `GOOGLE_API_KEY` is set as an environment variable or directly in the code for Gemini access. [3, 6, 11, 12, 16, 17]

import os
import asyncio
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from google.genai import types

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

from openinference.instrumentation.google_adk import GoogleADKInstrumentor

# Set your Google API Key (replace with your actual key or use env var)
os.environ["GOOGLE_API_KEY"] = os.environ.get("GOOGLE_API_KEY", "YOUR_GEMINI_API_KEY_HERE")

# 1. Configure OpenTelemetry Tracer Provider
# For simplicity, using ConsoleSpanExporter here. In a real app, use OTLPSpanExporter
# to send traces to an observability backend like Arize Phoenix, SigNoz, or Langfuse.
resource = Resource.create({"service.name": "my-adk-agent"})
tracer_provider = TracerProvider(resource=resource)

# To export to console (for quick verification):
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

# To export to an OTLP endpoint (e.g., a collector, Phoenix, SigNoz, Langfuse):
# endpoint = os.environ.get("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "http://localhost:4317")
# tracer_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter(endpoint)))

trace.set_tracer_provider(tracer_provider)

# 2. Instrument Google ADK
GoogleADKInstrumentor().instrument(tracer_provider=tracer_provider)

# 3. Define a sample Google ADK Agent
def get_current_time(city: str) -> dict:
    """Returns the current time for a specified city."""
    # This is a dummy tool, replace with actual logic
    return {"status": "success", "time": f"The current time in {city} is 12:00 PM."}

agent = Agent(
    name="TimeAgent",
    model="gemini-pro", # or "gemini-2.0-flash-exp" as per docs
    description="Agent to provide current time in a city.",
    instruction="You must use the get_current_time tool to find the answer.",
    tools=[get_current_time]
)

async def main():
    runner = InMemoryRunner(agent=agent)
    print("Agent started. Ask a question about time.")
    user_prompt = "What time is it in London?"
    print(f"User: {user_prompt}")
    response = await runner.run(types.Message(text=user_prompt))
    print(f"Agent: {response.text}")

    user_prompt_2 = "What about New York?"
    print(f"User: {user_prompt_2}")
    response_2 = await runner.run(types.Message(text=user_prompt_2))
    print(f"Agent: {response_2.text}")

if __name__ == "__main__":
    asyncio.run(main())