Auto-instrumentation

Use the opentelemetry-instrument wrapper:

opentelemetry-instrument \
    --traces_exporter console \
    --metrics_exporter console \
    python your_claude_agent_app.py

Manual Instrumentation

from opentelemetry.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor
from claude_agent_sdk import query
from claude_agent_sdk.types import ClaudeAgentOptions

ClaudeAgentSDKInstrumentor().instrument()

options = ClaudeAgentOptions(model="claude-3-5-sonnet-20241022", max_turns=5)

async def run_agent():
    async for message in query(prompt="Hello!", options=options):
        print(message)

ClaudeAgentSDKInstrumentor().uninstrument()

Export to OTLP Backend

export OTEL_SERVICE_NAME=my-claude-agent-app
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<trace_endpoint>
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=<metrics_endpoint>

opentelemetry-instrument python your_app.py

Content Capture

Control message content capture using environment variables:

# Enable experimental GenAI semantic conventions
export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

# Capture content in spans only
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY

# Capture content in events only
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=EVENT_ONLY

# Capture in both spans and events
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT

# Disable content capture (default)
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT

Using with Alibaba Cloud DashScope

This instrumentation works with Alibaba Cloud’s DashScope service via the Anthropic-compatible API endpoint:

import os

# Set environment variables for DashScope
os.environ["ANTHROPIC_BASE_URL"] = "https://dashscope.aliyuncs.com/apps/anthropic"
os.environ["ANTHROPIC_API_KEY"] = "your-dashscope-api-key"