instrument_google_genai docs (#1411)

Author: alexmojaki

docs/guides/web-ui/llm-panels.md

@@ -45,6 +45,7 @@ Click an LLM span to open the details panel.
 |---------------------------------------------------------------------------------------|--------------|-------|-------------------|
 | [Pydantic AI](../../integrations/llms/pydanticai.md)                                  | ✅            | ✅     | ✅                 |
 | [OpenAI](../../integrations/llms/openai.md)                                           | ✅            | ✅     | ✅                 |
+| [Google Gen AI](../../integrations/llms/google-genai.md)                              | ✅            | ✅     | ✅                 |
 | [LangChain](../../integrations/llms/langchain.md)                                     | ✅            | ✅     | ✅                 |
 | [Anthropic](../../integrations/llms/anthropic.md)                                     |              |       | ✅                 |
 | [Google ADK](https://github.com/pydantic/logfire/issues/1201#issuecomment-3012423974) | ✅            |       |                   |

docs/images/logfire-screenshot-google-genai-llm-panel.png

@@ -0,0 +1,37 @@
+---
+integration: logfire
+---
+# Google Gen AI SDK
+
+**Logfire** supports instrumenting calls to the [Google Gen AI SDK (`google-genai`)](https://googleapis.github.io/python-genai/) with the [`logfire.instrument_google_genai()`][logfire.Logfire.instrument_google_genai] method, for example:
+
+```python
+import os
+
+from google.genai import Client
+
+import logfire
+
+# This is required for prompts and completions to be captured in the spans
+os.environ['OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT'] = 'true'
+
+logfire.configure()
+logfire.instrument_google_genai()
+
+client = Client()
+response = client.models.generate_content(model='gemini-2.5-flash', contents=['Hi'])
+print(response.text)
+# Hello! How can I help you today?
+```
+
+This creates a span which shows the conversation in the Logfire UI:
+
+<figure markdown="span">
+![Logfire Google Gen AI conversation](../../images/logfire-screenshot-google-genai-llm-panel.png){ width="259" }
+</figure>
+
+!!! note
+    If you don't set the environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`
+    to `true`, the spans will simply contain `<elided>` where the prompts and completions would be.
+
+[`logfire.instrument_google_genai()`][logfire.Logfire.instrument_google_genai] uses the `GoogleGenAiSdkInstrumentor().instrument()` method of the [`opentelemetry-instrumentation-google-genai`](https://pypi.org/project/opentelemetry-instrumentation-google-genai/) package.

docs/integrations/llms/google-genai.md

@@ -30,7 +30,7 @@
     from .asgi import tweak_asgi_spans_tracer_provider
 except ImportError:
     raise RuntimeError(
-        'The `logfire.instrument_fastapi()` requires the `opentelemetry-instrumentation-fastapi` package.\n'
+        'The `logfire.instrument_fastapi()` method requires the `opentelemetry-instrumentation-fastapi` package.\n'
         'You can install this with:\n'
         "    pip install 'logfire[fastapi]'"
     )

logfire/_internal/integrations/fastapi.py

@@ -5,13 +5,22 @@
 from typing import Any
 
 from opentelemetry._events import Event, EventLogger, EventLoggerProvider
-from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
 from opentelemetry.trace import get_current_span
 from typing_extensions import TypeAlias
 
 import logfire
 from logfire._internal.utils import handle_internal_errors, safe_repr
 
+try:
+    from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
+except ImportError:
+    raise RuntimeError(
+        'The `logfire.instrument_google_genai()` method '
+        'requires the `opentelemetry-instrumentation-google-genai` package.\n'
+        'You can install this with:\n'
+        "    pip install 'logfire[google-genai]'"
+    )
+
 try:
     from opentelemetry.instrumentation.google_genai import dict_util
 
@@ -67,9 +76,12 @@ def get_event_logger(self, *args: Any, **kwargs: Any) -> SpanEventLogger:
         return SpanEventLogger(*args, **kwargs)
 
 
-def instrument_google_genai(logfire_instance: logfire.Logfire):
+def instrument_google_genai(logfire_instance: logfire.Logfire, **kwargs: Any):
     GoogleGenAiSdkInstrumentor().instrument(
-        event_logger_provider=SpanEventLoggerProvider(),
-        tracer_provider=logfire_instance.config.get_tracer_provider(),
-        meter_provider=logfire_instance.config.get_meter_provider(),
+        **{
+            'event_logger_provider': SpanEventLoggerProvider(),
+            'tracer_provider': logfire_instance.config.get_tracer_provider(),
+            'meter_provider': logfire_instance.config.get_meter_provider(),
+            **kwargs,
+        }
     )

logfire/_internal/integrations/google_genai.py

@@ -1280,11 +1280,21 @@ def instrument_anthropic(
             is_async_client,
         )
 
-    def instrument_google_genai(self):
+    def instrument_google_genai(self, **kwargs: Any):
+        """Instrument the [Google Gen AI SDK (`google-genai`)](https://googleapis.github.io/python-genai/).
+
+        !!! note
+            To capture message contents (i.e. prompts and completions), set the environment variable
+            `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` to `true`.
+
+        Uses the `GoogleGenAiSdkInstrumentor().instrument()` method of the
+        [`opentelemetry-instrumentation-google-genai`](https://pypi.org/project/opentelemetry-instrumentation-google-genai/)
+        package, to which it passes `**kwargs`.
+        """
         from .integrations.google_genai import instrument_google_genai
 
         self._warn_if_not_initialized_for_instrumentation()
-        instrument_google_genai(self)
+        instrument_google_genai(self, **kwargs)
 
     def instrument_litellm(self, **kwargs: Any):
         from .integrations.litellm import instrument_litellm

logfire/_internal/main.py

@@ -114,6 +114,7 @@ nav:
       - LLMs:
           - Pydantic AI: integrations/llms/pydanticai.md
           - OpenAI: integrations/llms/openai.md
+          - Google Gen AI: integrations/llms/google-genai.md
           - Anthropic: integrations/llms/anthropic.md
           - LangChain: integrations/llms/langchain.md
           - LLamaIndex: integrations/llms/llamaindex.md

mkdocs.yml

@@ -78,6 +78,7 @@ requests = ["opentelemetry-instrumentation-requests >= 0.42b0"]
 mysql = ["opentelemetry-instrumentation-mysql >= 0.42b0"]
 sqlite3 = ["opentelemetry-instrumentation-sqlite3 >= 0.42b0"]
 aws-lambda = ["opentelemetry-instrumentation-aws-lambda >= 0.42b0"]
+google-genai = ["opentelemetry-instrumentation-google-genai >= 0"]
 
 [project.urls]
 Homepage = "https://logfire.pydantic.dev/"

pyproject.toml

@@ -32,7 +32,7 @@ def test_missing_opentelemetry_dependency() -> None:
         with pytest.raises(RuntimeError) as exc_info:
             importlib.reload(logfire._internal.integrations.fastapi)
         assert str(exc_info.value) == snapshot("""\
-The `logfire.instrument_fastapi()` requires the `opentelemetry-instrumentation-fastapi` package.
+The `logfire.instrument_fastapi()` method requires the `opentelemetry-instrumentation-fastapi` package.
 You can install this with:
     pip install 'logfire[fastapi]'\
 """)

tests/otel_integrations/test_fastapi.py

@@ -1,6 +1,7 @@
 import os
 import sys
 import warnings
+from unittest import mock
 from unittest.mock import patch
 
 import pydantic
@@ -25,6 +26,17 @@
 ]
 
 
+def test_missing_opentelemetry_dependency() -> None:
+    with mock.patch.dict('sys.modules', {'opentelemetry.instrumentation.google_genai': None}):
+        with pytest.raises(RuntimeError) as exc_info:
+            logfire.instrument_google_genai()
+        assert str(exc_info.value) == snapshot("""\
+The `logfire.instrument_google_genai()` method requires the `opentelemetry-instrumentation-google-genai` package.
+You can install this with:
+    pip install 'logfire[google-genai]'\
+""")
+
+
 @pytest.mark.vcr()
 def test_instrument_google_genai(exporter: TestExporter) -> None:
     from google.genai import Client, types