OpenInference Google GenAI Instrumentation

0.1.15 · active · verified Wed Apr 15

This is a Python auto-instrumentation library designed to trace interactions with the Google GenAI SDK. It emits OpenTelemetry-compatible traces, providing observability for generative AI applications. These traces can be sent to any OpenTelemetry collector, such as Arize Phoenix, for analysis and visualization. The library is actively maintained with frequent updates.

Warnings

gotcha The Google GenAI SDK, which this library instruments, can encounter `google.api_core.exceptions.InternalServerError` when chat history grows too large, as the API may not gracefully handle internal quota limits. This is a limitation of the underlying Google GenAI API itself, not the instrumentation, but will manifest in your traced applications.
Fix: Manually manage chat history length to stay within API limitations. Consider summarizing or truncating older messages before sending new ones, or starting new chat sessions for long conversations.
gotcha As of version 0.1.15, the instrumentation may have limitations in fully tracing advanced features like complex tool calling scenarios (e.g., `tool_use_prompt_token_count` not included in `llm.token_count.prompt`) or the newer Google GenAI Interactions API. Support for these features is actively under development.
Fix: Check the official OpenInference GitHub repository for updates and newer versions that might include improved support. For critical agentic workflows, manual instrumentation might be necessary to capture full detail.
gotcha The OpenInference project and its instrumentations, including for Google GenAI, are rapidly evolving. While stable for core use cases, updates to the underlying Google GenAI SDK or OpenInference semantic conventions could introduce breaking changes or require adjustments to your tracing configuration.
Fix: Regularly review the official OpenInference documentation and GitHub changelog for breaking changes or important updates, especially before upgrading to new major or minor versions.

Install

pip install openinference-instrumentation-google-genai google-genai arize-otel With Arize OpenTelemetry Helper
pip install openinference-instrumentation-google-genai google-genai Minimal Install

Imports

GoogleGenAIInstrumentor

from openinference.instrumentation.google_genai import GoogleGenAIInstrumentor

Quickstart

This quickstart demonstrates how to install and configure `openinference-instrumentation-google-genai` to trace a simple multi-turn chat interaction using the Google GenAI SDK. It integrates with `arize-otel` for setting up the OpenTelemetry tracer provider, which then sends traces to a collector like Arize Phoenix. Remember to set your `GEMINI_API_KEY` and Arize credentials as environment variables.

import os
from openinference.instrumentation.google_genai import GoogleGenAIInstrumentor
from arize.otel import register
from google import genai

# Configure your Google GenAI API key
# It's recommended to set this as an environment variable
# os.environ["GEMINI_API_KEY"] = "your_gemini_api_key"

# Setup OpenTelemetry via Arize's convenience function
# Replace with your actual space_id, api_key, and project_name if using Arize
tracer_provider = register(
    space_id=os.environ.get('ARIZE_SPACE_ID', 'YOUR_ARIZE_SPACE_ID'),
    api_key=os.environ.get('ARIZE_API_KEY', 'YOUR_ARIZE_API_KEY'),
    project_name="my-genai-app",
)

# Instrument the Google GenAI client
GoogleGenAIInstrumentor().instrument(tracer_provider=tracer_provider)

# Ensure GEMINI_API_KEY is set for google-genai to function
if not os.environ.get("GEMINI_API_KEY"):
    print("Warning: GEMINI_API_KEY environment variable not set. Using a placeholder.")
    # This placeholder will likely cause authentication errors for actual API calls
    os.environ["GEMINI_API_KEY"] = "sk-your-gemini-api-key"

def send_message_multi_turn() -> tuple[str, str]:
    client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
    chat = client.chats.create(model="gemini-1.5-flash-001")
    response1 = chat.send_message("What is the capital of France?")
    response2 = chat.send_message("Why is the sky blue?")
    return response1.text or "", response2.text or ""

if __name__ == "__main__":
    print("Starting GenAI chat...")
    resp1_text, resp2_text = send_message_multi_turn()
    print(f"Response 1: {resp1_text}")
    print(f"Response 2: {resp2_text}")
    print("Traces should now be available in your configured OpenTelemetry collector (e.g., Arize Phoenix).")

view raw JSON →