Document InstrumentedModel (#1187)

Author: alexmojaki

docs/api/models/instrumented.md

@@ -0,0 +1,3 @@
+# pydantic_ai.models.instrumented
+
+::: pydantic_ai.models.instrumented

docs/api/models/wrapper.md

@@ -0,0 +1,3 @@
+# pydantic_ai.models.wrapper
+
+::: pydantic_ai.models.wrapper

docs/logfire.md

@@ -159,7 +159,7 @@ Note that the OpenTelemetry Semantic Conventions are still experimental and are
 
 ## Setting OpenTelemetry SDK providers
 
-By default, the global `TracerProvider` and `EventLoggerProvider` are used. These are set automatically by `logfire.configure()`. They can also be set by the `set_tracer_provider` and `set_event_logger_provider` functions in the OpenTelemetry Python SDK. You can set custom providers with `InstrumentationSettings`:
+By default, the global `TracerProvider` and `EventLoggerProvider` are used. These are set automatically by `logfire.configure()`. They can also be set by the `set_tracer_provider` and `set_event_logger_provider` functions in the OpenTelemetry Python SDK. You can set custom providers with [`InstrumentationSettings`][pydantic_ai.models.instrumented.InstrumentationSettings].
 
 ```python {title="instrumentation_settings_providers.py"}
 from opentelemetry.sdk._events import EventLoggerProvider
@@ -172,3 +172,14 @@ instrumentation_settings = InstrumentationSettings(
     event_logger_provider=EventLoggerProvider(),
 )
 ```
+
+## Instrumenting a specific `Model`
+
+```python {title="instrumented_model_example.py"}
+from pydantic_ai import Agent
+from pydantic_ai.models.instrumented import InstrumentationSettings, InstrumentedModel
+
+settings = InstrumentationSettings()
+model = InstrumentedModel('gpt-4o', settings)
+agent = Agent(model)
+```

mkdocs.yml

@@ -65,10 +65,12 @@ nav:
       - api/models/gemini.md
       - api/models/vertexai.md
       - api/models/groq.md
+      - api/models/instrumented.md
       - api/models/mistral.md
       - api/models/test.md
       - api/models/function.md
       - api/models/fallback.md
+      - api/models/wrapper.md
       - api/providers.md
       - api/pydantic_graph/graph.md
       - api/pydantic_graph/nodes.md

pydantic_ai_slim/pydantic_ai/agent.py

@@ -195,6 +195,7 @@ def __init__(
                 If this isn't set, then the last value set by
                 [`Agent.instrument_all()`][pydantic_ai.Agent.instrument_all]
                 will be used, which defaults to False.
+                See the [Debugging and Monitoring guide](https://ai.pydantic.dev/logfire/) for more info.
         """
         if model is None or defer_model_check:
             self.model = model
@@ -445,7 +446,7 @@ async def main():
         usage_limits = usage_limits or _usage.UsageLimits()
 
         if isinstance(model_used, InstrumentedModel):
-            tracer = model_used.options.tracer
+            tracer = model_used.settings.tracer
         else:
             tracer = NoOpTracer()
         agent_name = self.name or 'agent'

pydantic_ai_slim/pydantic_ai/models/instrumented.py

@@ -52,7 +52,9 @@ class InstrumentationSettings:
 
     - `Agent(instrument=...)`
     - [`Agent.instrument_all()`][pydantic_ai.agent.Agent.instrument_all]
-    - `InstrumentedModel`
+    - [`InstrumentedModel`][pydantic_ai.models.instrumented.InstrumentedModel]
+
+    See the [Debugging and Monitoring guide](https://ai.pydantic.dev/logfire/) for more info.
     """
 
     tracer: Tracer = field(repr=False)
@@ -94,17 +96,21 @@ def __init__(
 
 @dataclass
 class InstrumentedModel(WrapperModel):
-    """Model which is instrumented with OpenTelemetry."""
+    """Model which wraps another model so that requests are instrumented with OpenTelemetry.
+
+    See the [Debugging and Monitoring guide](https://ai.pydantic.dev/logfire/) for more info.
+    """
 
-    options: InstrumentationSettings
+    settings: InstrumentationSettings
+    """Configuration for instrumenting requests."""
 
     def __init__(
         self,
         wrapped: Model | KnownModelName,
         options: InstrumentationSettings | None = None,
     ) -> None:
         super().__init__(wrapped)
-        self.options = options or InstrumentationSettings()
+        self.settings = options or InstrumentationSettings()
 
     async def request(
         self,
@@ -156,7 +162,7 @@ def _instrument(
                 if isinstance(value := model_settings.get(key), (float, int)):
                     attributes[f'gen_ai.request.{key}'] = value
 
-        with self.options.tracer.start_as_current_span(span_name, attributes=attributes) as span:
+        with self.settings.tracer.start_as_current_span(span_name, attributes=attributes) as span:
 
             def finish(response: ModelResponse, usage: Usage):
                 if not span.is_recording():
@@ -190,9 +196,9 @@ def finish(response: ModelResponse, usage: Usage):
             yield finish
 
     def _emit_events(self, span: Span, events: list[Event]) -> None:
-        if self.options.event_mode == 'logs':
+        if self.settings.event_mode == 'logs':
             for event in events:
-                self.options.event_logger.emit(event)
+                self.settings.event_logger.emit(event)
         else:
             attr_name = 'events'
             span.set_attributes(

pydantic_ai_slim/pydantic_ai/models/wrapper.py

@@ -13,9 +13,13 @@
 
 @dataclass(init=False)
 class WrapperModel(Model):
-    """Model which wraps another model."""
+    """Model which wraps another model.
+
+    Does nothing on its own, used as a base class.
+    """
 
     wrapped: Model
+    """The underlying model being wrapped."""
 
     def __init__(self, wrapped: Model | KnownModelName):
         self.wrapped = infer_model(wrapped)

tests/test_logfire.py

@@ -230,14 +230,14 @@ def get_model():
     m = get_model()
     assert isinstance(m, InstrumentedModel)
     assert m.wrapped is model
-    assert m.options.event_mode == InstrumentationSettings().event_mode
+    assert m.settings.event_mode == InstrumentationSettings().event_mode
 
     options = InstrumentationSettings(event_mode='logs')
     Agent.instrument_all(options)
     m = get_model()
     assert isinstance(m, InstrumentedModel)
     assert m.wrapped is model
-    assert m.options is options
+    assert m.settings is options
 
     Agent.instrument_all(False)
     assert get_model() is model