Observability ด้วย OpenTelemetry

Export traces, metrics, และ events จาก Agent SDK ไปยัง observability backend ของคุณโดยใช้ OpenTelemetry

เมื่อคุณรัน agents ใน production คุณต้องการความชัดเจนในสิ่งที่พวกมันทำ:

tools ไหนที่พวกมันเรียก
แต่ละ model request ใช้เวลานานแค่ไหน
tokens ถูกใช้ไปเท่าไหร่
ความล้มเหลวเกิดขึ้นที่ไหน

Agent SDK สามารถ export ข้อมูลนี้เป็น OpenTelemetry traces, metrics, และ log events ไปยัง backend ใดก็ได้ที่ยอมรับ OpenTelemetry Protocol (OTLP) เช่น Honeycomb, Datadog, Grafana, Langfuse, หรือ self-hosted collector

วิธีการ Flow ของ Telemetry จาก SDK

Agent SDK รัน Claude Code CLI เป็น child process และสื่อสารกับมันผ่าน local pipe CLI มี OpenTelemetry instrumentation built in: มันบันทึก spans รอบแต่ละ model request และ tool execution, ส่ง metrics สำหรับ token และ cost counters, และส่ง structured log events สำหรับ prompts และ tool results

SDK เองไม่ผลิต telemetry ของตัวเอง แต่ส่งผ่าน configuration ไปยัง CLI process และ CLI export ตรงไปยัง collector ของคุณ

CLI export สาม OpenTelemetry signals ที่เป็นอิสระ แต่ละอันมี enable switch และ exporter ของตัวเอง:

Signal	สิ่งที่มี	เปิดใช้งานด้วย
Metrics	Counters สำหรับ tokens, cost, sessions, lines of code, และ tool decisions	`OTEL_METRICS_EXPORTER`
Log events	Structured records สำหรับแต่ละ prompt, API request, API error, และ tool result	`OTEL_LOGS_EXPORTER`
Traces	Spans สำหรับแต่ละ interaction, model request, tool call, และ hook (beta)	`OTEL_TRACES_EXPORTER` บวกกับ `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`

เปิดใช้งาน Telemetry Export

Telemetry จะปิดอยู่จนกว่าคุณจะตั้ง CLAUDE_CODE_ENABLE_TELEMETRY=1 และเลือก exporter อย่างน้อยหนึ่งตัว configuration ที่พบบ่อยที่สุดส่งสาม signals ทั้งหมดผ่าน OTLP HTTP ไปยัง collector:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

OTEL_ENV = {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    # จำเป็นสำหรับ traces ซึ่งอยู่ใน beta Metrics และ log events ไม่ต้องการสิ่งนี้
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    # เลือก exporter ต่อ signal ใช้ otlp สำหรับ SDK
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    # Standard OTLP transport configuration
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token",
}


async def main():
    options = ClaudeAgentOptions(env=OTEL_ENV)
    async for message in query(
        prompt="List the files in this directory", options=options
    ):
        print(message)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

const otelEnv = {
  CLAUDE_CODE_ENABLE_TELEMETRY: "1",
  CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1",
  OTEL_TRACES_EXPORTER: "otlp",
  OTEL_METRICS_EXPORTER: "otlp",
  OTEL_LOGS_EXPORTER: "otlp",
  OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf",
  OTEL_EXPORTER_OTLP_ENDPOINT: "http://collector.example.com:4318",
  OTEL_EXPORTER_OTLP_HEADERS: "Authorization=Bearer your-token",
};

for await (const message of query({
  prompt: "List the files in this directory",
  // env แทนที่ inherited environment ใน TypeScript ดังนั้น spread
  // process.env ก่อนเพื่อรักษา PATH, ANTHROPIC_API_KEY, และตัวแปรอื่นๆ
  options: { env: { ...process.env, ...otelEnv } },
})) {
  console.log(message);
}

note

Exporter console เขียน telemetry ไปยัง standard output ซึ่ง SDK ใช้เป็น message channel อย่าตั้ง console เป็นค่า exporter เมื่อรันผ่าน SDK เพื่อ inspect telemetry แบบ local ให้ชี้ OTEL_EXPORTER_OTLP_ENDPOINT ไปยัง local collector แทน

Flush telemetry จาก short-lived calls

CLI batch telemetry และ export ตาม interval บน clean process exit มันพยายาม flush pending data แต่ flush ถูกจำกัดด้วย timeout สั้นๆ ดังนั้น spans ยังสามารถถูก drop ได้

โดย default metrics export ทุก 60 วินาที และ traces กับ logs export ทุก 5 วินาที ตัวอย่างต่อไปนี้ลด intervals ทั้งสาม:

OTEL_ENV = {
    # ... exporter configuration ...
    "OTEL_METRIC_EXPORT_INTERVAL": "1000",
    "OTEL_LOGS_EXPORT_INTERVAL": "1000",
    "OTEL_TRACES_EXPORT_INTERVAL": "1000",
}

อ่าน Agent Traces

Traces ให้มุมมองที่ละเอียดที่สุดของการรัน agent แต่ละขั้นตอนของ agent loop กลายเป็น span ที่คุณสามารถ inspect ใน tracing backend ของคุณ:

claude_code.interaction: ครอบคลุม turn เดียวของ agent loop
claude_code.llm_request: ครอบคลุมแต่ละ call ไปยัง Claude API พร้อม model name, latency, และ token counts เป็น attributes
claude_code.tool: ครอบคลุมแต่ละ tool invocation พร้อม child spans สำหรับ permission wait และ execution
claude_code.hook: ครอบคลุมแต่ละ hook execution

Spans มี attribute session.id โดย default เมื่อคุณทำ query() calls หลายครั้งกับ session เดียวกัน filter บน session.id ใน backend เพื่อดูพวกมันเป็น timeline เดียว

note

Tracing อยู่ใน beta Span names และ attributes อาจเปลี่ยนแปลงระหว่าง releases

Link Traces ไปยัง Application ของคุณ

SDK auto-propagate W3C trace context เข้าไปใน CLI subprocess เมื่อคุณเรียก query() ขณะที่ OpenTelemetry span ถูก active ใน application ของคุณ SDK inject TRACEPARENT และ TRACESTATE เข้าไปใน child process environment และ CLI อ่านพวกมันเพื่อให้ span claude_code.interaction ของมันกลายเป็น child ของ span ของคุณ

Tag Telemetry จาก Agent ของคุณ

โดย default CLI รายงาน service.name เป็น claude-code หากคุณรัน agents หลายตัว ให้ override service name และเพิ่ม resource attributes:

options = ClaudeAgentOptions(
    env={
        # ... exporter configuration ...
        "OTEL_SERVICE_NAME": "support-triage-agent",
        "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production",
    },
)

ระบุ Actions ให้กับ End Users ของคุณ

เพื่อทำให้ tool calls และ MCP activity ระบุถึง end users ของ application ของคุณ inject end-user identity เป็น resource attributes บนแต่ละ query() call:

from urllib.parse import quote

options = ClaudeAgentOptions(
    env={
        # ... exporter configuration ...
        "OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}",
    },
)

const options = {
  env: {
    ...process.env,
    // ... exporter configuration ...
    OTEL_RESOURCE_ATTRIBUTES: `enduser.id=${encodeURIComponent(request.userId)},tenant.id=${encodeURIComponent(request.tenantId)}`,
  },
};

ควบคุมข้อมูล Sensitive ใน Exports

Telemetry เป็น structural โดย default เนื้อหาที่ agent ของคุณอ่านและเขียนไม่ถูกบันทึกโดย default ตัวแปร opt-in เหล่านี้เพิ่มเนื้อหาในข้อมูล exported:

ตัวแปร	เพิ่ม
`OTEL_LOG_USER_PROMPTS=1`	Prompt text บน `claude_code.user_prompt` events และบน `claude_code.interaction` span
`OTEL_LOG_TOOL_DETAILS=1`	Tool input arguments (file paths, shell commands, search patterns) บน `claude_code.tool_result` events
`OTEL_LOG_TOOL_CONTENT=1`	Full tool input และ output bodies เป็น span events บน `claude_code.tool` ตัดที่ 60 KB ต้องการให้ tracing เปิดใช้
`OTEL_LOG_RAW_API_BODIES`	Full Anthropic Messages API request และ response JSON เป็น log events

ปล่อยตัวแปรเหล่านี้ไม่ได้ตั้งค่าเว้นแต่ observability pipeline ของคุณได้รับการอนุมัติให้จัดเก็บข้อมูลที่ agent ของคุณจัดการ

เอกสารที่เกี่ยวข้อง

Track cost and usage: อ่าน token และ cost data จาก message stream โดยไม่ต้องใช้ external backend
Hosting the Agent SDK: deploy agents ใน containers ที่คุณสามารถตั้ง OpenTelemetry variables ที่ระดับ environment
Monitoring: reference ครบถ้วนสำหรับทุก environment variable, metric, และ event ที่ CLI ส่ง

วิธีการ Flow ของ Telemetry จาก SDK​

เปิดใช้งาน Telemetry Export​

Flush telemetry จาก short-lived calls​

อ่าน Agent Traces​

Link Traces ไปยัง Application ของคุณ​

Tag Telemetry จาก Agent ของคุณ​

ระบุ Actions ให้กับ End Users ของคุณ​

ควบคุมข้อมูล Sensitive ใน Exports​

เอกสารที่เกี่ยวข้อง​