v0.13.0: OpenTelemetry Observability with Langfuse Support

What's New

Built-in observer interface and OpenTelemetry instrumentation for tracing Claude agent sessions. Works with Langfuse, Jaeger, Datadog, or any OTel-compatible backend.

Observer Interface

• Observer module with on_user_prompt, on_message, on_error, on_close
• Register via ClaudeAgentOptions.new(observers: [...])
• Supports callable factories (-> { OTelObserver.new }) for thread-safe Rails/Puma/Sidekiq
• Observer errors silently rescued — never crashes the main pipeline

OpenTelemetry Observer

• ClaudeAgentSDK::Instrumentation::OTelObserver — require 'claude_agent_sdk/instrumentation'
• Span tree: claude_agent.session → claude_agent.generation + claude_agent.tool.*
• gen_ai.* + OpenInference semantic conventions (input.value, output.value, llm.model_name, llm.token_count.*)
• langfuse.observation.type set on all spans to enable Langfuse trace flow diagram (DAG)
• Lazy require 'opentelemetry' — zero cost for users who don't use it

Langfuse Setup (3 steps)

# 1. gem install opentelemetry-sdk opentelemetry-exporter-otlp
# 2. Configure OTel SDK with OTLP exporter pointed at Langfuse
# 3. Add observer:
observer = ClaudeAgentSDK::Instrumentation::OTelObserver.new
options = ClaudeAgentSDK::ClaudeAgentOptions.new(observers: [observer])
ClaudeAgentSDK.query(prompt: "Hello", options: options) { |msg| ... }

See the full setup guide in the README.

Also Changed

• README: comparison table fixes (sandbox-runtime row, Arize attribution)
• README: Rails OTel initializer patterns
• CLAUDE.md: observer/instrumentation architecture docs

Full Changelog: v0.12.0...v0.13.0