logfire.instrument_litellm() docs (#1415)

Author: alexmojaki

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

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

docs/images/logfire-screenshot-litellm-llm-panel.png

@@ -3,9 +3,17 @@ 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:
+**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.
 
-```python
+## Installation
+
+Install `logfire` with the `google-genai` extra:
+
+{{ install_logfire(extras=['google-genai']) }}
+
+## Usage
+
+```python hl_lines="8 11"
 import os
 
 from google.genai import Client

docs/integrations/llms/google-genai.md

@@ -1,12 +1,45 @@
 ---
-integration: third-party
+integration: logfire
 ---
+# LiteLLM
 
-LiteLLM allows you to call over 100 Large Language Models (LLMs) using the same input/output format. It also supports Logfire for logging and monitoring.
+**Logfire** supports instrumenting calls to the [LiteLLM](https://docs.litellm.ai/) Python SDK with the [`logfire.instrument_litellm()`][logfire.Logfire.instrument_litellm] method.
 
-To integrate Logfire with LiteLLM:
+## Installation
 
-1. Set the `LOGFIRE_TOKEN` environment variable.
-2. Add `logfire` to the callbacks of LiteLLM.
+Install `logfire` with the `litellm` extra:
 
-For more details, [check the official LiteLLM documentation.](https://docs.litellm.ai/docs/observability/logfire_integration)
+{{ install_logfire(extras=['litellm']) }}
+
+## Usage
+
+```python hl_lines="6"
+import litellm
+
+import logfire
+
+logfire.configure()
+logfire.instrument_litellm()
+
+response = litellm.completion(
+    model='gpt-4o-mini',
+    messages=[{'role': 'user', 'content': 'Hi'}],
+)
+print(response.choices[0].message.content)
+# > Hello! How can I assist you today?
+```
+
+!!! warning
+    This currently works best if all arguments of instrumented methods are passed as keyword arguments,
+    e.g. `litellm.completion(model=model, messages=messages)`.
+
+This creates a span which shows the conversation in the Logfire UI:
+
+<figure markdown="span">
+![Logfire LiteLLM conversation](../../images/logfire-screenshot-litellm-llm-panel.png){ width="697" }
+</figure>
+
+[`logfire.instrument_litellm()`][logfire.Logfire.instrument_litellm] uses the `LiteLLMInstrumentor().instrument()` method of the [`openinference-instrumentation-litellm`](https://pypi.org/project/openinference-instrumentation-litellm/) package.
+
+!!! note
+    [LiteLLM has its own integration with Logfire](https://docs.litellm.ai/docs/observability/logfire_integration), but we recommend using `logfire.instrument_litellm()` instead.

docs/integrations/llms/litellm.md

@@ -1,9 +1,17 @@
 from typing import Any
 
-from openinference.instrumentation.litellm import LiteLLMInstrumentor
-
 import logfire
 
+try:
+    from openinference.instrumentation.litellm import LiteLLMInstrumentor
+except ImportError:
+    raise RuntimeError(
+        'The `logfire.instrument_litellm()` method '
+        'requires the `openinference-instrumentation-litellm` package.\n'
+        'You can install this with:\n'
+        "    pip install 'logfire[litellm]'"
+    )
+
 
 def instrument_litellm(logfire_instance: logfire.Logfire, **kwargs: Any):
     LiteLLMInstrumentor().instrument(

logfire/_internal/integrations/litellm.py

@@ -1301,6 +1301,16 @@ def instrument_google_genai(self, **kwargs: Any):
         instrument_google_genai(self, **kwargs)
 
     def instrument_litellm(self, **kwargs: Any):
+        """Instrument the [LiteLLM](https://docs.litellm.ai/) Python SDK.
+
+        !!! warning
+            This currently works best if all arguments of instrumented methods are passed as keyword arguments,
+            e.g. `litellm.completion(model=model, messages=messages)`.
+
+        Uses the `LiteLLMInstrumentor().instrument()` method of the
+        [`openinference-instrumentation-litellm`](https://pypi.org/project/openinference-instrumentation-litellm/)
+        package, to which it passes `**kwargs`.
+        """
         from .integrations.litellm import instrument_litellm
 
         self._warn_if_not_initialized_for_instrumentation()

logfire/_internal/main.py

@@ -117,10 +117,10 @@ nav:
           - Google Gen AI: integrations/llms/google-genai.md
           - Anthropic: integrations/llms/anthropic.md
           - LangChain: integrations/llms/langchain.md
+          - LiteLLM: integrations/llms/litellm.md
           - MCP: integrations/llms/mcp.md
           - LLamaIndex: integrations/llms/llamaindex.md
           - Mirascope: integrations/llms/mirascope.md
-          - LiteLLM: integrations/llms/litellm.md
           - Magentic: integrations/llms/magentic.md
       - Web Frameworks:
           - Web Frameworks: integrations/web-frameworks/index.md

mkdocs.yml

@@ -2,6 +2,7 @@
 import logging
 import warnings
 from typing import Any
+from unittest import mock
 
 import pydantic
 import pytest
@@ -14,6 +15,17 @@
 from logfire.testing import TestExporter
 
 
+def test_missing_opentelemetry_dependency() -> None:
+    with mock.patch.dict('sys.modules', {'openinference.instrumentation.litellm': None}):
+        with pytest.raises(RuntimeError) as exc_info:
+            logfire.instrument_litellm()
+        assert str(exc_info.value) == snapshot("""\
+The `logfire.instrument_litellm()` method requires the `openinference-instrumentation-litellm` package.
+You can install this with:
+    pip install 'logfire[litellm]'\
+""")
+
+
 @pytest.mark.vcr()
 @pytest.mark.skipif(get_version(pydantic.__version__) < get_version('2.5.0'), reason='Requires newer pydantic version')
 def test_litellm_instrumentation(exporter: TestExporter) -> None: