{"id":14788,"library":"opentelemetry-instrumentation-google-genai","title":"OpenTelemetry Instrumentation for Google GenAI","description":"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.","status":"active","version":"0.7b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-google-genai","tags":["opentelemetry","instrumentation","observability","google-genai","ai","llm","tracing","metrics"],"install":[{"cmd":"pip install opentelemetry-instrumentation-google-genai","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"Core OpenTelemetry API for tracing and metrics.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry SDK for providers, processors, and exporters.","package":"opentelemetry-sdk","optional":false},{"reason":"Base package for OpenTelemetry instrumentations.","package":"opentelemetry-instrumentation","optional":false},{"reason":"Provides standard attribute names for OpenTelemetry data, including GenAI conventions.","package":"opentelemetry-semantic-conventions","optional":false},{"reason":"Utility functions for GenAI instrumentations within OpenTelemetry.","package":"opentelemetry-util-genai","optional":false},{"reason":"The Google Generative AI client library which this package instruments.","package":"google-generativeai","optional":false}],"imports":[{"symbol":"GoogleGenAIInstrumentor","correct":"from opentelemetry.instrumentation.google_genai import GoogleGenAIInstrumentor"}],"quickstart":{"code":"import os\nimport google.generativeai as genai\n\nfrom opentelemetry import trace\nfrom opentelemetry.instrumentation.google_genai import GoogleGenAIInstrumentor\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\n\n# 1. Configure OpenTelemetry SDK\nresource = Resource.create(attributes={\n    \"service.name\": \"my-genai-app\",\n    \"application.name\": \"google-gemini-example\"\n})\nprovider = TracerProvider(resource=resource)\n# For local testing, use ConsoleSpanExporter to print traces to console\nprovider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(provider)\n\n# 2. Enable Google GenAI instrumentation\nGoogleGenAIInstrumentor().instrument()\n\n# 3. Configure Google Generative AI\n# Ensure GEMINI_API_KEY environment variable is set or pass directly\napi_key = os.environ.get('GEMINI_API_KEY', 'YOUR_API_KEY_HERE')\nif not api_key or api_key == 'YOUR_API_KEY_HERE':\n    print(\"Warning: GEMINI_API_KEY environment variable not set. API calls might fail.\")\ngenai.configure(api_key=api_key)\n\n# 4. Use Google GenAI - this will now be instrumented\nprint(\"\\n--- Generating Content ---\")\ntracer = trace.get_tracer(__name__)\nwith tracer.start_as_current_span(\"generate-story\"): # Custom span to wrap GenAI call\n    model = genai.GenerativeModel('gemini-pro')\n    try:\n        response = model.generate_content(\"Tell me a short, imaginative story about a cat who learns to fly.\")\n        print(\"Generated story:\\n\" + response.text)\n    except Exception as e:\n        print(f\"Error generating content: {e}\")\n\nprint(\"\\n--- Traces (if configured) should appear above/below ---\")","lang":"python","description":"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."},"warnings":[{"fix":"Always review release notes for the `opentelemetry-instrumentation-google-genai` package and related `opentelemetry-semantic-conventions` for potential breaking changes when upgrading.","message":"This 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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Upgrade to `opentelemetry-instrumentation-google-genai==0.7b0` or newer to ensure correct token counting for streaming responses.","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.7b0"},{"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.","message":"Custom 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.","severity":"gotcha","affected_versions":"<0.6b0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[],"ecosystem":"pypi"}