Registry / observability / opentelemetry-instrumentation-google-genai

opentelemetry-instrumentation-google-genai

JSON →
library0.7b1pypiunverified

This OpenTelemetry instrumentation provides automatic tracing and metrics for applications using Google's Generative AI client library (`google-generativeai`). It captures details like model calls, prompts, and responses, aligning with OpenTelemetry's GenAI semantic conventions. As part of the `opentelemetry-python-contrib` project, it is currently in beta (`0.7b0`) and subject to rapid development and potential API changes.

pip install opentelemetry-instrumentation-google-genai
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-google-genai
observabilityenv0.7b1
Install
2.7s avg
Import
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.7b1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.7MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.7s · import 0.000s · 23MB
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GoogleGenAIInstrumentor
from opentelemetry.instrumentation.google_genai import GoogleGenAIInstrumentor

This quickstart demonstrates how to enable OpenTelemetry instrumentation for Google Generative AI. It sets up a basic OpenTelemetry SDK with a console exporter, then initializes the `GoogleGenAIInstrumentor`. Ensure `GEMINI_API_KEY` is set in your environment for the GenAI client to function.

import os import google.generativeai as genai from opentelemetry import trace from opentelemetry.instrumentation.google_genai import GoogleGenAIInstrumentor from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor # 1. Configure OpenTelemetry SDK resource = Resource.create(attributes={ "service.name": "my-genai-app", "application.name": "google-gemini-example" }) provider = TracerProvider(resource=resource) # For local testing, use ConsoleSpanExporter to print traces to console provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter())) trace.set_tracer_provider(provider) # 2. Enable Google GenAI instrumentation GoogleGenAIInstrumentor().instrument() # 3. Configure Google Generative AI # Ensure GEMINI_API_KEY environment variable is set or pass directly api_key = os.environ.get('GEMINI_API_KEY', 'YOUR_API_KEY_HERE') if not api_key or api_key == 'YOUR_API_KEY_HERE': print("Warning: GEMINI_API_KEY environment variable not set. API calls might fail.") genai.configure(api_key=api_key) # 4. Use Google GenAI - this will now be instrumented print("\n--- Generating Content ---") tracer = trace.get_tracer(__name__) with tracer.start_as_current_span("generate-story"): # Custom span to wrap GenAI call model = genai.GenerativeModel('gemini-pro') try: response = model.generate_content("Tell me a short, imaginative story about a cat who learns to fly.") print("Generated story:\n" + response.text) except Exception as e: print(f"Error generating content: {e}") print("\n--- Traces (if configured) should appear above/below ---")
Debug
Known issues
breakingThis instrumentation is currently in beta (`0.7b0`) as part of `opentelemetry-python-contrib`. This means its API, behavior, and emitted attributes are subject to change without strict adherence to semantic versioning until a stable `1.0.0` release.
fix
Always review release notes for the `opentelemetry-instrumentation-google-genai` package and related `opentelemetry-semantic-conventions` for potential breaking changes when upgrading.
affects: <1.0.0
gotchaPrior to version `0.7b0`, there was a known bug where token counts for streaming `generateContent` methods might be inaccurate. If relying on token metrics for cost or rate limiting, ensure you are on `0.7b0` or later.
fix
Upgrade to `opentelemetry-instrumentation-google-genai==0.7b0` or newer to ensure correct token counting for streaming responses.
affects: <0.7b0
gotchaCustom attributes cannot be added to `generate_content {model.name}` spans or `gen_ai.client.inference.operation.details` log events via the OpenTelemetry Context API prior to version `0.6b0`. Attempting to do so on older versions will have no effect.
fix
Upgrade to `opentelemetry-instrumentation-google-genai==0.6b0` or newer to utilize the Context API for adding custom attributes to GenAI spans and log events.
affects: <0.6b0
gotchaThe instrumentation relies on the `google-generativeai` library. Ensure this library is installed alongside the OpenTelemetry instrumentation and properly configured with an API key, as the instrumentation itself does not handle API key management or client initialization.
fix
Install `google-generativeai` (`pip install google-generativeai`) and configure your API key (e.g., `genai.configure(api_key=os.environ.get('GEMINI_API_KEY'))`) before making any GenAI calls.
affects: All
Upgrade
Version history
0.7b1latest on PyPI · released May 19, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API for tracing and metrics.
opentelemetry-sdkrequiredOpenTelemetry SDK for providers, processors, and exporters.
opentelemetry-instrumentationrequiredBase package for OpenTelemetry instrumentations.
opentelemetry-semantic-conventionsrequiredProvides standard attribute names for OpenTelemetry data, including GenAI conventions.
opentelemetry-util-genairequiredUtility functions for GenAI instrumentations within OpenTelemetry.
google-generativeairequiredThe Google Generative AI client library which this package instruments.
Agent activity
22 hits · last 30 days
node
20
OpenAI (training)
1
Resources

No resource links recorded.