Claude SDK instrumentation (#1618)

Co-authored-by: Copilot <[email protected]>

Author: alexmojaki

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

@@ -53,6 +53,7 @@ Click an LLM span to open the details panel.
 | [LangChain](../../integrations/llms/langchain.md)                                     | ✅            | ✅     | ✅                 |
 | [LiteLLM](../../integrations/llms/litellm.md)                                         | ✅            | ✅     | ✅                 |
 | [Anthropic](../../integrations/llms/anthropic.md)                                     |              |       | ✅                 |
+| [Claude Agent SDK](../../integrations/llms/claude-agent-sdk.md)                       |              |       | ✅                 |
 | [Google ADK](https://github.com/pydantic/logfire/issues/1201#issuecomment-3012423974) | ✅            |       |                   |
 
 Tokens and costs are more generally supported by any instrumentation that follows the standard [OpenTelemetry semantic conventions for GenAI spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/). The following snippet shows the attributes required if you want to log the data manually:

docs/images/logfire-screenshot-claude-agent-sdk.png

@@ -45,6 +45,9 @@ With that you get:
 
 ## Methods covered
 
+!!! note
+    This is separate from [Claude Agent SDK instrumentation](../llms/claude-agent-sdk.md). The Claude Agent SDK doesn't actually use the `anthropic` package under the hood.
+
 The following Anthropic methods are covered:
 
 - [`client.messages.create`](https://docs.anthropic.com/en/api/messages)

docs/integrations/llms/anthropic.md

@@ -0,0 +1,89 @@
+---
+title: "Logfire Integrations: Claude Agent SDK"
+description: "Guide for using Logfire with Claude Agent SDK via Langsmith OpenTelemetry tracing, including setup instructions and example trace output."
+integration: "third-party"
+---
+# Claude Agent SDK
+
+You can instrument the Python [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) using **Logfire** and [Langsmith](https://docs.langchain.com/langsmith/trace-claude-agent-sdk).
+
+!!! note
+    This is separate from the [`anthropic` integration](../llms/anthropic.md). The Claude Agent SDK doesn't actually use the `anthropic` package under the hood.
+
+First, install dependencies:
+
+```bash
+pip install 'langsmith[claude-agent-sdk, otel]'
+```
+
+Here's an example script:
+
+```python
+from langsmith.integrations.claude_agent_sdk import configure_claude_agent_sdk
+import logfire
+import os
+import asyncio
+from claude_agent_sdk import (
+    ClaudeAgentOptions,
+    ClaudeSDKClient,
+    tool,
+    create_sdk_mcp_server,
+)
+from typing import Any
+
+# These environment variables enable Langsmith OpenTelemetry tracing,
+# instead of sending traces to Langsmith directly.
+os.environ['LANGSMITH_OTEL_ENABLED'] = "true"
+os.environ['LANGSMITH_OTEL_ONLY'] = "true"
+os.environ['LANGSMITH_TRACING'] = "true"
+
+# Ensure that OpenTelemetry traces are sent to Logfire
+logfire.configure()
+
+# Instrument the Claude Agent SDK with Langsmith
+configure_claude_agent_sdk()
+
+# Example of using a tool in the Claude Agent SDK:
+@tool(
+    "get_weather",
+    "Gets the current weather for a given city",
+    {
+        "city": str,
+    },
+)
+async def get_weather(args: dict[str, Any]) -> dict[str, Any]:
+    """Simulated weather lookup tool"""
+    city = args["city"]
+    weather = "Cloudy, 59°F"
+    return {"content": [{"type": "text", "text": f"Weather in {city}: {weather}"}]}
+
+
+async def main():
+    weather_server = create_sdk_mcp_server(
+        name="weather",
+        version="1.0.0",
+        tools=[get_weather],
+    )
+
+    options = ClaudeAgentOptions(
+        system_prompt="You are a friendly travel assistant who helps with weather information.",
+        mcp_servers={"weather": weather_server},
+        allowed_tools=["mcp__weather__get_weather"],
+    )
+
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query("What's the weather like in Berlin?")
+
+        async for message in client.receive_response():
+            print(message)
+
+
+asyncio.run(main())
+```
+
+!!! warning
+    Only the `ClaudeSDKClient` is instrumented, not the top-level `claude_agent_sdk.query()` function.
+
+The resulting trace looks like this in Logfire:
+
+![Logfire Claude Agent SDK Trace](../../images/logfire-screenshot-claude-agent-sdk.png)

docs/integrations/llms/claude-agent-sdk.md

@@ -5,10 +5,11 @@ integration: "built-in"
 ---
 # LangChain
 
-[LangChain](https://www.langchain.com/) (and thus [LangGraph](https://www.langchain.com/langgraph)) has [built-in OpenTelemetry tracing via Langsmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_langchain_with_otel) which you can use with **Logfire**. It's enabled by these two environment variables:
+[LangChain](https://www.langchain.com/) (and thus [LangGraph](https://www.langchain.com/langgraph)) has [built-in OpenTelemetry tracing via Langsmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_langchain_with_otel) which you can use with **Logfire**. It's enabled by these environment variables:
 
 ```
 LANGSMITH_OTEL_ENABLED=true
+LANGSMITH_OTEL_ONLY=true
 LANGSMITH_TRACING=true
 ```
 
@@ -21,6 +22,7 @@ import logfire
 
 # These environment variables need to be set before importing langchain or langgraph
 os.environ['LANGSMITH_OTEL_ENABLED'] = 'true'
+os.environ["LANGSMITH_OTEL_ONLY"] = 'true'
 os.environ['LANGSMITH_TRACING'] = 'true'
 
 from langchain.agents import create_agent

docs/integrations/llms/langchain.md

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+from collections.abc import Mapping
 from contextlib import suppress
 from dataclasses import dataclass
 from typing import Any, cast
@@ -347,7 +348,8 @@ def _transform_langchain_span(span: ReadableSpanDict):
     if existing_json_schema:  # pragma: no cover
         return
 
-    properties = JsonSchemaProperties({})
+    properties = JsonSchemaProperties({'all_messages_events': {'type': 'array'}})
+
     parsed_attributes: dict[str, Any] = {}
     for key, value in attributes.items():
         if not isinstance(value, str) or not value.startswith(('{"', '[')):
@@ -359,6 +361,18 @@ def _transform_langchain_span(span: ReadableSpanDict):
         # Tell the Logfire backend to parse this attribute as JSON.
         properties[key] = {'type': 'object' if value.startswith('{') else 'array'}
 
+    attributes, new_attributes = _transform_langsmith_span_attributes(attributes, parsed_attributes)
+
+    span['attributes'] = {
+        **attributes,
+        ATTRIBUTES_JSON_SCHEMA_KEY: attributes_json_schema(properties),
+        **new_attributes,
+    }
+
+
+def _transform_langsmith_span_attributes(
+    attributes: Mapping[str, Any], parsed_attributes: dict[str, Any]
+) -> tuple[Mapping[str, Any], dict[str, Any]]:
     new_attributes: dict[str, Any] = {}
 
     # OTel semconv attributes, needed for displaying costs.
@@ -370,7 +384,7 @@ def _transform_langchain_span(span: ReadableSpanDict):
         ]
         new_attributes.setdefault('gen_ai.request.model', model)
 
-    request_model: str = attributes.get('gen_ai.request.model') or new_attributes.get('gen_ai.request.model', '')  # type: ignore
+    request_model: str = attributes.get('gen_ai.request.model') or new_attributes.get('gen_ai.request.model', '')
 
     if not request_model and 'gen_ai.usage.input_tokens' in attributes:  # pragma: no cover
         # Only keep usage attributes on spans with actual token usage, i.e. model requests,
@@ -389,18 +403,31 @@ def _transform_langchain_span(span: ReadableSpanDict):
 
     # Add `all_messages_events`
     with suppress(Exception):
-        input_messages = parsed_attributes.get('input.value', parsed_attributes.get('gen_ai.prompt', {}))['messages']
-        if len(input_messages) == 1 and isinstance(input_messages[0], list):
-            [input_messages] = input_messages
-
+        input_attribute = parsed_attributes.get('input.value', parsed_attributes.get('gen_ai.prompt', {}))
+        if 'messages' in input_attribute:
+            input_messages = input_attribute['messages']
+            if len(input_messages) == 1 and isinstance(input_messages[0], list):
+                [input_messages] = input_messages
+        else:
+            input_messages: list[Any] = []
+            if 'system' in input_attribute:
+                input_messages.append({'role': 'system', 'content': input_attribute['system']})
+            if 'prompt' in input_attribute:
+                input_messages.append({'role': 'user', 'content': input_attribute['prompt']})
+        if not input_messages:
+            raise ValueError
         message_events = [_transform_langchain_message(old_message) for old_message in input_messages]
 
         # If we fail to parse output messages, fine, but only try if we've succeeded to parse input messages.
         with suppress(Exception):
             output_value = parsed_attributes.get('output.value', parsed_attributes.get('gen_ai.completion', {}))
+            # This weird issubclass usage is because pyright can't deal with missing type arguments of dict sensibly.
+            if issubclass(type(output_value), dict) and 'content' in output_value and 'role' in output_value:
+                output_value = cast(Any, {'messages': [output_value]})
             try:
                 # Multiple generations mean multiple choices, we can only display one.
-                message_events += [_transform_langchain_message(output_value['generations'][0][0]['message'])]
+                old_message = output_value['generations'][0][0]['message']
+                message_events += [_transform_langchain_message(old_message)]
             except Exception:
                 try:
                     output_message_events = [_transform_langchain_message(m) for m in output_value['messages']]
@@ -420,13 +447,8 @@ def _transform_langchain_span(span: ReadableSpanDict):
                     message_events += [_transform_langchain_message(output_value['output'])]
 
         new_attributes['all_messages_events'] = json.dumps(message_events)
-        properties['all_messages_events'] = {'type': 'array'}
 
-    span['attributes'] = {
-        **attributes,
-        ATTRIBUTES_JSON_SCHEMA_KEY: attributes_json_schema(properties),
-        **new_attributes,
-    }
+    return attributes, new_attributes
 
 
 def _transform_langchain_message(old_message: dict[str, Any]) -> dict[str, Any]:
@@ -446,6 +468,9 @@ def _transform_langchain_message(old_message: dict[str, Any]) -> dict[str, Any]:
         'role': role,
     }
 
+    if 'tool_call_id' in result:
+        result['id'] = result.pop('tool_call_id')
+
     if tool_calls := result.get('tool_calls'):
         for tool_call in tool_calls:
             if (
@@ -463,9 +488,9 @@ def _transform_langchain_message(old_message: dict[str, Any]) -> dict[str, Any]:
                 )
     else:
         result.pop('tool_calls', None)
+        if role == 'tool' and 'content' in result and 'id' in result:
+            result.setdefault('name', '')  # dummy value which makes the frontend happy
 
-    if 'tool_call_id' in result:
-        result['id'] = result.pop('tool_call_id')
     return result
 
 

logfire/_internal/exporters/processor_wrapper.py

@@ -155,6 +155,8 @@ class BaseScrubber(ABC):
         'rpc.method',
         'gen_ai.system',
         'model_request_parameters',
+        'langsmith.metadata.session_id',
+        'langsmith.trace.session_name',
     }
 
     @abstractmethod

logfire/_internal/scrubbing.py

@@ -121,6 +121,7 @@ nav:
           - LangChain: integrations/llms/langchain.md
           - LiteLLM: integrations/llms/litellm.md
           - MCP: integrations/llms/mcp.md
+          - Claude Agent SDK: integrations/llms/claude-agent-sdk.md
           - LLamaIndex: integrations/llms/llamaindex.md
           - Mirascope: integrations/llms/mirascope.md
           - Magentic: integrations/llms/magentic.md
@@ -244,11 +245,11 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
-          paths: [src/packages/logfire/logfire]
+          paths: [ src/packages/logfire/logfire ]
           options:
             members_order: source
             separate_signature: true
-            filters: ["!^_"]
+            filters: [ "!^_" ]
             docstring_options:
               ignore_init_summary: true
             merge_init_into_class: true