- tools mana yang mereka panggil
- berapa lama setiap permintaan model memakan waktu
- berapa banyak tokens yang dihabiskan
- di mana kegagalan terjadi
Untuk Claude API atau Managed Agents, lihat OpenTelemetry untuk Claude API.
Bagaimana telemetry mengalir dari SDK
Agent SDK menjalankan Claude Code CLI sebagai child process dan berkomunikasi dengannya melalui local pipe. CLI memiliki instrumentasi OpenTelemetry built-in: ia merekam spans di sekitar setiap permintaan model dan eksekusi tool, memancarkan metrics untuk token dan cost counters, dan memancarkan structured log events untuk prompts dan tool results. SDK tidak menghasilkan telemetry sendiri. Sebaliknya, ia melewatkan konfigurasi ke CLI process, dan CLI mengekspor langsung ke collector Anda. Konfigurasi dilewatkan sebagai environment variables. Secara default, child process mewarisi environment aplikasi Anda, jadi Anda dapat mengonfigurasi telemetry di salah satu dari dua tempat:- Process environment: atur variables di shell, container, atau orchestrator Anda sebelum aplikasi Anda dimulai. Setiap panggilan
query()mengambilnya secara otomatis tanpa perubahan kode. Ini adalah pendekatan yang direkomendasikan untuk production deployments. - Per-call options: atur variables di
ClaudeAgentOptions.env(Python) atauoptions.env(TypeScript). Gunakan ini ketika agents yang berbeda dalam proses yang sama memerlukan pengaturan telemetry yang berbeda. Di Python,envdigabungkan di atas environment yang diwarisi. Di TypeScript,envmenggantikan environment yang diwarisi sepenuhnya, jadi sertakan...process.envdalam object yang Anda lewatkan.
Untuk daftar lengkap nama metric, nama event, dan attributes, lihat referensi Claude Code Monitoring. Agent SDK memancarkan data yang sama karena menjalankan CLI yang sama. Nama span tercantum dalam Read agent traces di bawah.
Aktifkan ekspor telemetry
Telemetry dimatikan sampai Anda mengaturCLAUDE_CODE_ENABLE_TELEMETRY=1 dan memilih setidaknya satu exporter. Konfigurasi paling umum mengirim ketiga sinyal melalui OTLP HTTP ke collector.
Contoh berikut mengatur variables dalam dictionary dan meneruskannya melalui options.env. Agent menjalankan satu task, dan CLI mengekspor spans, metrics, dan events ke collector di collector.example.com sementara loop mengonsumsi response stream:
options.env sepenuhnya.
Untuk mengonfirmasi bahwa ekspor berfungsi, periksa log collector Anda untuk incoming spans, metrics, dan log events setelah task selesai. CLI gagal diam-diam pada export errors secara default: jika endpoint tidak dapat dijangkau atau menolak data, agent masih berjalan normal dan CLI menghapus telemetry tanpa menampilkan error di aplikasi Anda. Untuk menampilkan exporter errors, atur CLAUDE_CODE_OTEL_DIAG_STDERR=1 bersama dengan exporter variables dan baca diagnostics melalui callback stderr SDK (Python) atau opsi stderr (TypeScript). Memerlukan Claude Code v2.1.179 atau lebih baru.
Exporter
console menulis telemetry ke standard output, yang digunakan SDK sebagai message channel-nya. Jangan atur console sebagai nilai exporter saat menjalankan melalui SDK. Untuk menginspeksi telemetry secara lokal, arahkan OTEL_EXPORTER_OTLP_ENDPOINT ke local OpenTelemetry Collector sebagai gantinya.Flush telemetry dari short-lived calls
CLI melakukan batch telemetry dan mengekspor pada interval. Pada clean process exit, ia mencoba untuk flush pending data, tetapi flush dibatasi oleh timeout pendek, jadi spans masih dapat dijatuhkan jika collector lambat merespons. Jika proses Anda dibunuh sebelum CLI shutdown, apa pun yang masih dalam batch buffer hilang. Menurunkan export intervals mengurangi kedua window. Secara default, metrics mengekspor setiap 60 detik dan traces dan logs mengekspor setiap 5 detik. Contoh berikut mempersingkat ketiga interval sehingga data mencapai collector sementara task pendek masih berjalan:Baca agent traces
Traces memberikan Anda tampilan paling detail dari agent run. DenganCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 diatur, setiap langkah dari agent loop menjadi span yang dapat Anda inspeksi di backend tracing Anda:
claude_code.interaction: membungkus satu turn dari agent loop, dari menerima prompt hingga menghasilkan response.claude_code.llm_request: membungkus setiap panggilan ke Claude API, dengan model name, latency, dan token counts sebagai attributes.claude_code.tool: membungkus setiap tool invocation, dengan child spans untuk permission wait (claude_code.tool.blocked_on_user) dan execution itu sendiri (claude_code.tool.execution).claude_code.hook: membungkus setiap eksekusi hook. Memerlukan detailed beta tracing (ENABLE_BETA_TRACING_DETAILED=1danBETA_TRACING_ENDPOINT), sepasang yang juga mengubah ke mana logs dan traces Anda pergi.
llm_request, tool, dan hook adalah children dari enclosing claude_code.interaction span. Ketika agent menghasilkan subagent melalui Agent tool, spans llm_request dan tool subagent bersarang di bawah claude_code.tool span parent agent, jadi full delegation chain muncul sebagai satu trace.
Spans membawa atribut session.id secara default. Ketika Anda membuat beberapa panggilan query() terhadap session yang sama, filter pada session.id di backend Anda untuk melihatnya sebagai satu timeline. Claude Code menghilangkan atribut jika Anda mengatur OTEL_METRICS_INCLUDE_SESSION_ID ke falsy value.
Tracing dalam beta. Nama span dan attributes dapat berubah antar releases. Lihat
Traces (beta) dalam referensi Monitoring
untuk variabel konfigurasi trace exporter.
Hubungkan traces ke aplikasi Anda
SDK secara otomatis menyebarkan W3C trace context ke CLI subprocess. Ketika Anda memanggilquery() sementara OpenTelemetry span aktif di aplikasi Anda, SDK menyuntikkan TRACEPARENT dan TRACESTATE ke environment child process, dan CLI membacanya sehingga span claude_code.interaction-nya menjadi child dari span Anda. Agent run kemudian muncul di dalam trace aplikasi Anda alih-alih sebagai root yang terputus.
Catatan log event OTLP yang dipancarkan selama run membawa konteks trace yang sama: dengan TRACEPARENT diatur, trace_id dan span_id setiap record cocok dengan trace aplikasi Anda, sehingga Anda dapat menggabungkan events ke spans di backend Anda. Sebelum v2.1.212, catatan event yang dipancarkan di luar span aktif tidak membawa trace_id atau span_id.
Ketika trace-context propagation diaktifkan, CLI juga meneruskan TRACEPARENT ke setiap command Bash dan PowerShell yang dijalankannya. Jika command yang diluncurkan melalui Bash tool memancarkan spans OpenTelemetry-nya sendiri, spans tersebut bersarang di bawah span claude_code.tool.execution yang membungkus command.
Auto-injection dilewati ketika Anda mengatur TRACEPARENT secara eksplisit dalam options.env, jadi Anda dapat menyematkan parent context spesifik jika diperlukan. Interactive CLI sessions mengabaikan inbound TRACEPARENT sepenuhnya; hanya Agent SDK dan claude -p runs yang menghormatinya. Lihat Traces (beta) dalam referensi Monitoring untuk referensi span dan attribute lengkap.
Tag telemetry dari agent Anda
Secara default, CLI melaporkanservice.name sebagai claude-code. Jika Anda menjalankan beberapa agents, atau menjalankan SDK bersama services lain yang mengekspor ke collector yang sama, override service name dan tambahkan resource attributes sehingga Anda dapat memfilter berdasarkan agent di backend Anda.
Contoh berikut mengganti nama service dan melampirkan deployment metadata. Nilai-nilai ini diterapkan sebagai OpenTelemetry resource attributes pada setiap span, metric, dan event yang agent pancarkan:
Atribusikan actions ke end users Anda
CLI melampirkan identity attributes ke setiap event berdasarkan credential yang digunakan untuk memanggil Anthropic. Ketika Anda membangun aplikasi yang melayani banyak end users dari satu deployment, attributes ini mengidentifikasi credential service Anda, bukan end user atas nama siapa agent bertindak. Untuk membuat tool calls dan MCP activity dapat diatribusikan ke end users aplikasi Anda, suntikkan end-user identity sebagai resource attributes pada setiap panggilanquery(). Percent-encode values sebelum menginterpolasikannya, karena OTEL_RESOURCE_ATTRIBUTES reserves commas, spaces, dan equals signs. Contoh berikut melampirkan requesting user dan tenant ke setiap span dan event dari satu request. Ini mengasumsikan objek request dari web framework Anda yang membawa user dan tenant IDs:
tool_decision, tool_result, mcp_server_connection, dan permission_mode_changed, yang diekspor sebagai log records yang dinamai dengan prefix claude_code., menjadi per-user audit trail yang dapat Anda teruskan ke platform Security Information and Event Management (SIEM). Lihat Audit security events dalam referensi Monitoring untuk daftar lengkap security-relevant events dan attributes yang masing-masing membawa.
Kontrol sensitive data dalam exports
Telemetry bersifat structural secara default. Durations, model names, dan tool names dicatat pada setiap span; token counts dicatat ketika underlying API request mengembalikan usage data, jadi spans untuk failed atau aborted requests dapat menghilangkannya. Konten yang dibaca dan ditulis agent Anda tidak dicatat secara default. Variables opt-in ini menambahkan konten ke exported data:
Biarkan unset kecuali pipeline observability Anda disetujui untuk menyimpan data yang ditangani agent Anda. Lihat Security and privacy dalam referensi Monitoring untuk daftar lengkap attributes dan redaction behavior.
Dokumentasi terkait
Panduan-panduan ini mencakup topik-topik yang berdekatan untuk monitoring dan deploying agents:- Lacak biaya dan penggunaan: baca token dan cost data dari message stream tanpa backend eksternal.
- Hosting Agent SDK: deploy agents dalam containers di mana Anda dapat mengatur OpenTelemetry variables pada level environment.
- Monitoring: referensi lengkap untuk setiap environment variable, metric, dan event yang CLI pancarkan.