Add include_binary_content flag to InstrumentationSettings, rename OTel attribute key from content to binary_content for BinaryParts (#1739)

Author: alexmojaki

docs/logfire.md

@@ -238,9 +238,11 @@ print(result.output)
 #> Paris
 ```
 
-## Data format
+## Advanced usage
 
-PydanticAI follows the [OpenTelemetry Semantic Conventions for Generative AI systems](https://opentelemetry.io/docs/specs/semconv/gen-ai/), with one caveat. The semantic conventions specify that messages should be captured as individual events (logs) that are children of the request span. By default, PydanticAI instead collects these events into a JSON array which is set as a single large attribute called `events` on the request span. To change this, use [`InstrumentationSettings(event_mode='logs')`][pydantic_ai.agent.InstrumentationSettings].
+### Configuring data format
+
+PydanticAI follows the [OpenTelemetry Semantic Conventions for Generative AI systems](https://opentelemetry.io/docs/specs/semconv/gen-ai/), with one caveat. The semantic conventions specify that messages should be captured as individual events (logs) that are children of the request span. By default, PydanticAI instead collects these events into a JSON array which is set as a single large attribute called `events` on the request span. To change this, use `event_mode='logs'`:
 
 ```python {title="instrumentation_settings_event_mode.py"}
 import logfire
@@ -261,23 +263,27 @@ If you have very long conversations, the `events` span attribute may be truncate
 
 Note that the OpenTelemetry Semantic Conventions are still experimental and are likely to change.
 
-## Setting OpenTelemetry SDK providers
+### 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`][pydantic_ai.models.instrumented.InstrumentationSettings].
 
 ```python {title="instrumentation_settings_providers.py"}
 from opentelemetry.sdk._events import EventLoggerProvider
 from opentelemetry.sdk.trace import TracerProvider
 
-from pydantic_ai.agent import InstrumentationSettings
+from pydantic_ai.agent import Agent, InstrumentationSettings
 
 instrumentation_settings = InstrumentationSettings(
     tracer_provider=TracerProvider(),
     event_logger_provider=EventLoggerProvider(),
 )
+
+agent = Agent('gpt-4o', instrument=instrumentation_settings)
+# or to instrument all agents:
+Agent.instrument_all(instrumentation_settings)
 ```
 
-## Instrumenting a specific `Model`
+### Instrumenting a specific `Model`
 
 ```python {title="instrumented_model_example.py"}
 from pydantic_ai import Agent
@@ -287,3 +293,15 @@ settings = InstrumentationSettings()
 model = InstrumentedModel('gpt-4o', settings)
 agent = Agent(model)
 ```
+
+### Excluding binary content
+
+```python {title="excluding_binary_content.py"}
+from pydantic_ai.agent import Agent, InstrumentationSettings
+
+instrumentation_settings = InstrumentationSettings(include_binary_content=False)
+
+agent = Agent('gpt-4o', instrument=instrumentation_settings)
+# or to instrument all agents:
+Agent.instrument_all(instrumentation_settings)
+```

pydantic_ai_slim/pydantic_ai/agent.py

@@ -654,8 +654,10 @@ async def main():
         usage_limits = usage_limits or _usage.UsageLimits()
 
         if isinstance(model_used, InstrumentedModel):
+            instrumentation_settings = model_used.settings
             tracer = model_used.settings.tracer
         else:
+            instrumentation_settings = None
             tracer = NoOpTracer()
         agent_name = self.name or 'agent'
         run_span = tracer.start_span(
@@ -723,19 +725,18 @@ async def get_instructions(run_context: RunContext[AgentDepsT]) -> str | None:
                     )
         finally:
             try:
-                if run_span.is_recording():
-                    run_span.set_attributes(self._run_span_end_attributes(state, usage))
+                if instrumentation_settings and run_span.is_recording():
+                    run_span.set_attributes(self._run_span_end_attributes(state, usage, instrumentation_settings))
             finally:
                 run_span.end()
 
-    def _run_span_end_attributes(self, state: _agent_graph.GraphAgentState, usage: _usage.Usage):
+    def _run_span_end_attributes(
+        self, state: _agent_graph.GraphAgentState, usage: _usage.Usage, settings: InstrumentationSettings
+    ):
         return {
             **usage.opentelemetry_attributes(),
             'all_messages_events': json.dumps(
-                [
-                    InstrumentedModel.event_to_dict(e)
-                    for e in InstrumentedModel.messages_to_otel_events(state.message_history)
-                ]
+                [InstrumentedModel.event_to_dict(e) for e in settings.messages_to_otel_events(state.message_history)]
             ),
             'logfire.json_schema': json.dumps(
                 {

pydantic_ai_slim/pydantic_ai/messages.py

@@ -6,7 +6,7 @@
 from dataclasses import dataclass, field, replace
 from datetime import datetime
 from mimetypes import guess_type
-from typing import Annotated, Any, Literal, Union, cast, overload
+from typing import TYPE_CHECKING, Annotated, Any, Literal, Union, cast, overload
 
 import pydantic
 import pydantic_core
@@ -17,6 +17,10 @@
 from .exceptions import UnexpectedModelBehavior
 from .usage import Usage
 
+if TYPE_CHECKING:
+    from .models.instrumented import InstrumentationSettings
+
+
 AudioMediaType: TypeAlias = Literal['audio/wav', 'audio/mpeg']
 ImageMediaType: TypeAlias = Literal['image/jpeg', 'image/png', 'image/gif', 'image/webp']
 DocumentMediaType: TypeAlias = Literal[
@@ -68,7 +72,7 @@ class SystemPromptPart:
     part_kind: Literal['system-prompt'] = 'system-prompt'
     """Part type identifier, this is available on all parts as a discriminator."""
 
-    def otel_event(self) -> Event:
+    def otel_event(self, _settings: InstrumentationSettings) -> Event:
         return Event('gen_ai.system.message', body={'content': self.content, 'role': 'system'})
 
 
@@ -305,7 +309,7 @@ class UserPromptPart:
     part_kind: Literal['user-prompt'] = 'user-prompt'
     """Part type identifier, this is available on all parts as a discriminator."""
 
-    def otel_event(self) -> Event:
+    def otel_event(self, settings: InstrumentationSettings) -> Event:
         content: str | list[dict[str, Any] | str]
         if isinstance(self.content, str):
             content = self.content
@@ -317,8 +321,10 @@ def otel_event(self) -> Event:
                 elif isinstance(part, (ImageUrl, AudioUrl, DocumentUrl, VideoUrl)):
                     content.append({'kind': part.kind, 'url': part.url})
                 elif isinstance(part, BinaryContent):
-                    base64_data = base64.b64encode(part.data).decode()
-                    content.append({'kind': part.kind, 'content': base64_data, 'media_type': part.media_type})
+                    converted_part = {'kind': part.kind, 'media_type': part.media_type}
+                    if settings.include_binary_content:
+                        converted_part['binary_content'] = base64.b64encode(part.data).decode()
+                    content.append(converted_part)
                 else:
                     content.append({'kind': part.kind})
         return Event('gen_ai.user.message', body={'content': content, 'role': 'user'})
@@ -361,7 +367,7 @@ def model_response_object(self) -> dict[str, Any]:
         else:
             return {'return_value': tool_return_ta.dump_python(self.content, mode='json')}
 
-    def otel_event(self) -> Event:
+    def otel_event(self, _settings: InstrumentationSettings) -> Event:
         return Event(
             'gen_ai.tool.message',
             body={'content': self.content, 'role': 'tool', 'id': self.tool_call_id, 'name': self.tool_name},
@@ -418,7 +424,7 @@ def model_response(self) -> str:
             description = f'{len(self.content)} validation errors: {json_errors.decode()}'
         return f'{description}\n\nFix the errors and try again.'
 
-    def otel_event(self) -> Event:
+    def otel_event(self, _settings: InstrumentationSettings) -> Event:
         if self.tool_name is None:
             return Event('gen_ai.user.message', body={'content': self.model_response(), 'role': 'user'})
         else:

pydantic_ai_slim/pydantic_ai/models/instrumented.py

@@ -77,13 +77,15 @@ class InstrumentationSettings:
     tracer: Tracer = field(repr=False)
     event_logger: EventLogger = field(repr=False)
     event_mode: Literal['attributes', 'logs'] = 'attributes'
+    include_binary_content: bool = True
 
     def __init__(
         self,
         *,
         event_mode: Literal['attributes', 'logs'] = 'attributes',
         tracer_provider: TracerProvider | None = None,
         event_logger_provider: EventLoggerProvider | None = None,
+        include_binary_content: bool = True,
     ):
         """Create instrumentation options.
 
@@ -97,6 +99,7 @@ def __init__(
                 If not provided, the global event logger provider is used.
                 Calling `logfire.configure()` sets the global event logger provider, so most users don't need this.
                 This is only used if `event_mode='logs'`.
+            include_binary_content: Whether to include binary content in the instrumentation events.
         """
         from pydantic_ai import __version__
 
@@ -105,6 +108,40 @@ def __init__(
         self.tracer = tracer_provider.get_tracer('pydantic-ai', __version__)
         self.event_logger = event_logger_provider.get_event_logger('pydantic-ai', __version__)
         self.event_mode = event_mode
+        self.include_binary_content = include_binary_content
+
+    def messages_to_otel_events(self, messages: list[ModelMessage]) -> list[Event]:
+        """Convert a list of model messages to OpenTelemetry events.
+
+        Args:
+            messages: The messages to convert.
+
+        Returns:
+            A list of OpenTelemetry events.
+        """
+        events: list[Event] = []
+        instructions = InstrumentedModel._get_instructions(messages)  # pyright: ignore [reportPrivateUsage]
+        if instructions is not None:
+            events.append(Event('gen_ai.system.message', body={'content': instructions, 'role': 'system'}))
+
+        for message_index, message in enumerate(messages):
+            message_events: list[Event] = []
+            if isinstance(message, ModelRequest):
+                for part in message.parts:
+                    if hasattr(part, 'otel_event'):
+                        message_events.append(part.otel_event(self))
+            elif isinstance(message, ModelResponse):
+                message_events = message.otel_events()
+            for event in message_events:
+                event.attributes = {
+                    'gen_ai.message.index': message_index,
+                    **(event.attributes or {}),
+                }
+            events.extend(message_events)
+
+        for event in events:
+            event.body = InstrumentedModel.serialize_any(event.body)
+        return events
 
 
 GEN_AI_SYSTEM_ATTRIBUTE = 'gen_ai.system'
@@ -193,8 +230,8 @@ def finish(response: ModelResponse):
                 if not span.is_recording():
                     return
 
-                events = self.messages_to_otel_events(messages)
-                for event in self.messages_to_otel_events([response]):
+                events = self.settings.messages_to_otel_events(messages)
+                for event in self.settings.messages_to_otel_events([response]):
                     events.append(
                         Event(
                             'gen_ai.choice',
@@ -270,32 +307,6 @@ def event_to_dict(event: Event) -> dict[str, Any]:
             body = {'body': event.body}
         return {**body, **(event.attributes or {})}
 
-    @staticmethod
-    def messages_to_otel_events(messages: list[ModelMessage]) -> list[Event]:
-        events: list[Event] = []
-        instructions = InstrumentedModel._get_instructions(messages)
-        if instructions is not None:
-            events.append(Event('gen_ai.system.message', body={'content': instructions, 'role': 'system'}))
-
-        for message_index, message in enumerate(messages):
-            message_events: list[Event] = []
-            if isinstance(message, ModelRequest):
-                for part in message.parts:
-                    if hasattr(part, 'otel_event'):
-                        message_events.append(part.otel_event())
-            elif isinstance(message, ModelResponse):
-                message_events = message.otel_events()
-            for event in message_events:
-                event.attributes = {
-                    'gen_ai.message.index': message_index,
-                    **(event.attributes or {}),
-                }
-            events.extend(message_events)
-
-        for event in events:
-            event.body = InstrumentedModel.serialize_any(event.body)
-        return events
-
     @staticmethod
     def serialize_any(value: Any) -> str:
         try:

tests/models/test_instrumented.py

@@ -675,7 +675,8 @@ def __repr__(self):
         ModelRequest(parts=[ToolReturnPart('tool', Bar(), tool_call_id='return_tool_call_id')]),
     ]
 
-    assert [InstrumentedModel.event_to_dict(e) for e in InstrumentedModel.messages_to_otel_events(messages)] == [
+    settings = InstrumentationSettings()
+    assert [InstrumentedModel.event_to_dict(e) for e in settings.messages_to_otel_events(messages)] == [
         {
             'body': "{'role': 'assistant', 'tool_calls': [{'id': 'tool_call_id', 'type': 'function', 'function': {'name': 'tool', 'arguments': {'arg': Foo()}}}]}",
             'gen_ai.message.index': 0,
@@ -694,9 +695,8 @@ def test_messages_to_otel_events_instructions():
         ModelRequest(instructions='instructions', parts=[UserPromptPart('user_prompt')]),
         ModelResponse(parts=[TextPart('text1')]),
     ]
-    assert [
-        InstrumentedModel.event_to_dict(e) for e in InstrumentedModel.messages_to_otel_events(messages)
-    ] == snapshot(
+    settings = InstrumentationSettings()
+    assert [InstrumentedModel.event_to_dict(e) for e in settings.messages_to_otel_events(messages)] == snapshot(
         [
             {'content': 'instructions', 'role': 'system', 'event.name': 'gen_ai.system.message'},
             {'content': 'user_prompt', 'role': 'user', 'gen_ai.message.index': 0, 'event.name': 'gen_ai.user.message'},
@@ -716,9 +716,8 @@ def test_messages_to_otel_events_instructions_multiple_messages():
         ModelResponse(parts=[TextPart('text1')]),
         ModelRequest(instructions='instructions2', parts=[UserPromptPart('user_prompt2')]),
     ]
-    assert [
-        InstrumentedModel.event_to_dict(e) for e in InstrumentedModel.messages_to_otel_events(messages)
-    ] == snapshot(
+    settings = InstrumentationSettings()
+    assert [InstrumentedModel.event_to_dict(e) for e in settings.messages_to_otel_events(messages)] == snapshot(
         [
             {'content': 'instructions2', 'role': 'system', 'event.name': 'gen_ai.system.message'},
             {'content': 'user_prompt', 'role': 'user', 'gen_ai.message.index': 0, 'event.name': 'gen_ai.user.message'},
@@ -755,9 +754,8 @@ def test_messages_to_otel_events_image_url(document_content: BinaryContent):
         ModelRequest(parts=[UserPromptPart(content=['user_prompt6', document_content])]),
         ModelResponse(parts=[TextPart('text1')]),
     ]
-    assert [
-        InstrumentedModel.event_to_dict(e) for e in InstrumentedModel.messages_to_otel_events(messages)
-    ] == snapshot(
+    settings = InstrumentationSettings()
+    assert [InstrumentedModel.event_to_dict(e) for e in settings.messages_to_otel_events(messages)] == snapshot(
         [
             {
                 'content': ['user_prompt', {'kind': 'image-url', 'url': 'https://example.com/image.png'}],
@@ -796,7 +794,10 @@ def test_messages_to_otel_events_image_url(document_content: BinaryContent):
                 'event.name': 'gen_ai.user.message',
             },
             {
-                'content': ['user_prompt6', {'kind': 'binary', 'content': IsStr(), 'media_type': 'application/pdf'}],
+                'content': [
+                    'user_prompt6',
+                    {'kind': 'binary', 'binary_content': IsStr(), 'media_type': 'application/pdf'},
+                ],
                 'role': 'user',
                 'gen_ai.message.index': 5,
                 'event.name': 'gen_ai.user.message',
@@ -809,3 +810,20 @@ def test_messages_to_otel_events_image_url(document_content: BinaryContent):
             },
         ]
     )
+
+
+def test_messages_to_otel_events_without_binary_content(document_content: BinaryContent):
+    messages: list[ModelMessage] = [
+        ModelRequest(parts=[UserPromptPart(content=['user_prompt6', document_content])]),
+    ]
+    settings = InstrumentationSettings(include_binary_content=False)
+    assert [InstrumentedModel.event_to_dict(e) for e in settings.messages_to_otel_events(messages)] == snapshot(
+        [
+            {
+                'content': ['user_prompt6', {'kind': 'binary', 'media_type': 'application/pdf'}],
+                'role': 'user',
+                'gen_ai.message.index': 0,
+                'event.name': 'gen_ai.user.message',
+            }
+        ]
+    )