Pemantauan

Pelajari cara mengaktifkan dan mengonfigurasi OpenTelemetry untuk Claude Code.

Lacak penggunaan Claude Code, biaya, dan aktivitas tool di seluruh organisasi Anda dengan mengekspor data telemetri melalui OpenTelemetry (OTel). Claude Code mengekspor metrik sebagai data deret waktu melalui protokol metrik standar, acara melalui protokol log/acara, dan secara opsional distributed traces melalui OpenTelemetry.

[!NOTE]

Untuk Claude API atau Managed Agents, lihat OpenTelemetry untuk Claude API.

Mulai cepat

Konfigurasikan OpenTelemetry menggunakan variabel lingkungan:

# 1. Aktifkan telemetri
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Pilih pengekspor (keduanya bersifat opsional - konfigurasikan hanya yang Anda butuhkan)
export OTEL_METRICS_EXPORTER=otlp       # Opsi: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Opsi: otlp, console, none

# 3. Konfigurasikan titik akhir OTLP (untuk pengekspor OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Atur autentikasi (jika diperlukan)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Untuk debugging: kurangi interval ekspor, dan atur ulang untuk penggunaan produksi
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 detik (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 detik (default: 5000ms)

# 6. Jalankan Claude Code
claude

Untuk memverifikasi pengaturan yang mengekspor metrik, periksa backend Anda untuk metrik claude_code.session.count, yang Claude Code keluarkan saat sesi dimulai. Untuk memverifikasi pengaturan hanya log, kirimkan prompt dan periksa acara claude_code.user_prompt.

Jika tidak ada yang tiba, jalankan Claude Code dengan claude --debug-file <path> dan periksa log yang ditulisnya ke jalur tersebut. Claude Code melaporkan kegagalan dari pengekspor yang Anda konfigurasikan sebagai kesalahan [3P telemetry], di mana 3P berarti pihak ketiga. Baris yang diawali dengan [Anthropic telemetry] menjelaskan telemetri operasional terpisah Anthropic dan tidak menunjukkan masalah dengan pengaturan Anda.

Untuk opsi konfigurasi lengkap, lihat spesifikasi OpenTelemetry.

Konfigurasi administrator

Administrator dapat mengonfigurasi pengaturan OpenTelemetry untuk semua pengguna melalui file pengaturan terkelola. Lihat prioritas pengaturan untuk informasi lebih lanjut tentang bagaimana pengaturan diterapkan.

Contoh konfigurasi pengaturan terkelola:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Dalam aplikasi Claude Desktop, sesi tab Code membaca pengaturan terkelola ini dari sumber yang menjangkau setiap jenis sesi Desktop. Formulir OpenTelemetry untuk Cowork di bawah Monitoring dalam pengaturan Data dan privasi konsol admin berlaku hanya untuk sesi Cowork, jadi baik CLI terminal maupun tab Code tidak mengekspor ke kolektor yang Anda tetapkan di sana.

Claude Code mengabaikan variabel pengekspor OpenTelemetry dalam .claude/settings.json dan .claude/settings.local.json repositori, jadi repositori tidak dapat menggunakannya untuk menghidupkan telemetri, memilih ke mana telemetri pergi, atau menangkap konten. Atur variabel tersebut dalam pengaturan terkelola, atau biarkan setiap pengembang mengaturnya dalam shell atau ~/.claude/settings.json mereka. Repositori masih dapat mematikan sinyal dengan menetapkan pemilih pengekspor, seperti OTEL_LOGS_EXPORTER, ke none, kecuali pengaturan terkelola, file --settings, atau lingkungan tempat Anda memulai Claude Code menetapkan variabel tersebut.

Claude Code tidak meneruskan variabel lingkungan OTEL_* ke subproses yang dihasilkannya, termasuk alat Bash, hooks, server MCP, dan language servers. Aplikasi yang diinstrumentasi OpenTelemetry yang Anda jalankan melalui alat Bash tidak mewarisi titik akhir pengekspor atau header Claude Code, jadi atur variabel tersebut langsung dalam perintah jika aplikasi itu perlu mengekspor telemetrinya sendiri.

Bagaimana pengaturan terkelola mengunci tujuan OTLP

Ketika Anda menetapkan variabel OTEL_EXPORTER_OTLP_* dalam pengaturan terkelola, Claude Code menghapus variabel yang ditetapkan pengembang yang bertentangan saat startup dan mencatat peringatan dalam debug log. Apa yang dihapusnya tergantung pada variabel mana yang Anda tetapkan:

• Endpoints: ketika Anda menetapkan OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code menghapus setiap titik akhir per-sinyal yang ditetapkan pengembang. Pengembang tidak dapat mengarahkan satu sinyal ke kolektor yang berbeda, jadi Anda tidak perlu juga menetapkan variabel titik akhir per-sinyal dalam pengaturan terkelola.

• Protokol: ketika Anda menetapkan OTEL_EXPORTER_OTLP_PROTOCOL, Claude Code menghapus setiap protokol per-sinyal yang ditetapkan pengembang.

• Kredensial: ketika Anda menetapkan OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY, atau OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, Claude Code menghapus versi per-sinyal dari variabel tersebut yang ditetapkan pengembang, ditambah setiap variabel titik akhir yang ditetapkan pengembang, generik atau per-sinyal, karena kredensial tersebut akan mencapai kolektor yang tidak dipilih pengaturan terkelola.

• Pemilih pengekspor: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, dan OTEL_TRACES_EXPORTER beta mengikuti prioritas per-kunci normal. Pengaturan pengembang masih dapat menonaktifkan sinyal atau mengalihkannya ke pengekspor konsol, jadi tetapkan pemilih dalam pengaturan terkelola juga jika Anda perlu menguncinya. Di seluruh sumber admin, OTEL_LOGS_EXPORTER mengikuti unit telemetri sementara dua pemilih lainnya digabungkan per kunci. Memerlukan Claude Code v2.1.223 atau lebih baru.

• Titik akhir pelacakan beta: dengan pelacakan beta terperinci aktif, Claude Code mengekspor log dan jejak ke BETA_TRACING_ENDPOINT alih-alih melalui pengekspor log dan jejak. Claude Code oleh karena itu menghapus BETA_TRACING_ENDPOINT yang ditetapkan pengembang kapan pun salah satu pengaturan terkelola ini memutuskan tujuan sinyal:

  • Titik akhir atau kredensial generik atau log/jejak
  • Sebuah otelHeadersHelper
  • Pemilih pengekspor log atau jejak yang ditetapkan ke none, console, atau kosong, nilai yang membuat sinyal tetap di luar kolektor
  • CLAUDE_CODE_ENABLE_TELEMETRY dimatikan

  Titik akhir atau kredensial khusus metrik tidak menghapusnya. Sebelum v2.1.251, BETA_TRACING_ENDPOINT yang ditetapkan pengembang mengarahkan ulang log dan jejak yang diekspor pelacakan beta terperinci bahkan ketika pengaturan terkelola menyematkan kolektor.

Claude Code tidak menghapus variabel per-sinyal yang Anda tetapkan dalam pengaturan terkelola itu sendiri, jadi Anda dapat merutekan satu sinyal ke kolektor yang berbeda dengan menetapkan variabelnya di sana, seperti yang dilakukan contoh SIEM. Jika Anda menetapkan kredensial per-sinyal di sana, Claude Code menghapus titik akhir yang ditetapkan pengembang untuk sinyal itu.

Perilaku penghapusan ini mengubah di mana telemetri dikirimkan, bukan apa yang dikumpulkan Claude Code.

Sebelum v2.1.217, setiap variabel mengikuti prioritas pengaturan per-kunci secara independen, jadi titik akhir khusus sinyal yang ditetapkan dalam pengaturan pengguna atau shell mengarahkan ulang sinyal itu dari kolektor terkelola.

Ketika aplikasi desktop atau pelari lingkungan yang di-host sendiri meluncurkan Claude Code dan menamai titik akhir OTLP dalam lingkungan yang disediakannya, Claude Code menyematkan tujuan dengan cara yang sama: variabel telemetri peluncur menghapus variabel yang ditetapkan pengembang persis seperti pengaturan terkelola. Claude Code tidak menghapus variabel yang ditetapkan peluncur itu sendiri. Memerlukan Claude Code v2.1.251 atau lebih baru.

Detail konfigurasi

Variabel konfigurasi umum

Variabel-variabel ini mengonfigurasi eksporter, endpoint, dan perilaku ekspor untuk semua deployment.

Jika Anda menetapkan variabel endpoint atau protokol per-sinyal, seperti OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, Claude Code menggunakannya sebagai pengganti variabel generik untuk sinyal tersebut. Jika Anda menetapkan variabel header per-sinyal, seperti OTEL_EXPORTER_OTLP_METRICS_HEADERS, Claude Code menggabungkannya dengan OTEL_EXPORTER_OTLP_HEADERS generik untuk sinyal tersebut.

Pada mesin dengan pengaturan terkelola, lihat Bagaimana pengaturan terkelola mengunci tujuan OTLP untuk mengetahui apa yang Claude Code hapus.

Untuk protokol http/protobuf dan http/json, Claude Code mengirim setiap permintaan ekspor dengan header Content-Length.

Autentikasi mTLS

Cara Anda mengonfigurasi sertifikat klien untuk eksporter OTLP tergantung pada protokol OTLP yang digunakan untuk sinyal tersebut, diatur melalui OTEL_EXPORTER_OTLP_PROTOCOL atau penggantian spesifik sinyal. Konfigurasi yang sama berlaku untuk metrik, log, dan jejak.

Untuk grpc, SDK OpenTelemetry membaca variabel OTLP standar secara langsung, jadi konfigurasi yang ada yang menetapkan variabel metrik spesifik sinyal terus berfungsi. Pada mesin dengan pengaturan terkelola, Claude Code dapat menghapus kredensial dan endpoint spesifik sinyal yang ditetapkan pengembang saat startup.

Kontrol kardinalitas metrik

Variabel lingkungan berikut mengontrol atribut mana yang disertakan dalam metrik untuk mengelola kardinalitas:

Kardinalitas yang lebih rendah umumnya berarti kinerja yang lebih baik dan biaya penyimpanan yang lebih rendah tetapi data yang kurang granular untuk analisis.

Traces (beta)

Distributed tracing mengekspor span yang menghubungkan setiap prompt pengguna ke permintaan API dan eksekusi alat yang dipicunya, sehingga Anda dapat melihat permintaan lengkap sebagai jejak tunggal di backend tracing Anda.

Tracing dimatikan secara default. Untuk mengaktifkannya, atur CLAUDE_CODE_ENABLE_TELEMETRY=1 dan CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, kemudian atur OTEL_TRACES_EXPORTER untuk memilih tempat span dikirim. Traces menggunakan kembali konfigurasi OTLP umum untuk endpoint, protokol, header, dan mTLS. Pada mesin dengan pengaturan terkelola, Claude Code dapat menghapus kredensial dan endpoint spesifik sinyal yang ditetapkan pengembang saat startup.

Span menyembunyikan teks prompt pengguna, detail input alat, dan konten alat secara default. Atur OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1, dan OTEL_LOG_TOOL_CONTENT=1 untuk menyertakannya.

Ketika tracing aktif, subproses Bash dan PowerShell secara otomatis mewarisi variabel lingkungan TRACEPARENT yang berisi konteks jejak W3C dari span eksekusi alat yang aktif. Ini memungkinkan subproses apa pun yang membaca TRACEPARENT untuk membuat span-nya sendiri sebagai anak dari jejak yang sama, memungkinkan distributed tracing end-to-end melalui skrip dan perintah yang Claude jalankan.

Ketika tracing aktif dan Claude Code terhubung langsung ke API Anthropic, setiap permintaan model membawa header W3C traceparent yang diatur ke konteks span claude_code.llm_request, dan header traceresponse API dicatat sebagai link span. Bersama-sama ini menghubungkan span sisi klien Claude Code ke jejak sisi server melalui perantara yang sesuai. Permintaan HTTP MCP keluar membawa traceparent dengan cara yang sama. Header tidak dikirim ke penyedia pihak ketiga.

Secara default, header traceparent pada permintaan model dan HTTP MCP dikirim hanya ketika ANTHROPIC_BASE_URL tidak diatur atau menunjuk ke API Anthropic, karena beberapa proxy menolak header yang tidak dikenali. Variabel TRACEPARENT subproses dikendalikan oleh switch yang sama untuk konsistensi. Jika Anda menjalankan Claude Code melalui proxy ANTHROPIC_BASE_URL kustom dan ingin konteks jejak dipropagasi, atur CLAUDE_CODE_PROPAGATE_TRACEPARENT=1.

Dalam sesi Agent SDK dan non-interaktif yang dimulai dengan -p, Claude Code juga membaca TRACEPARENT dan TRACESTATE dari lingkungannya sendiri saat memulai setiap span interaksi. Ini memungkinkan proses embedding melewatkan konteks jejak W3C aktifnya ke subproses sehingga span Claude Code muncul sebagai anak dari jejak distributed pemanggil. Sesi interaktif mengabaikan TRACEPARENT masuk untuk menghindari secara tidak sengaja mewarisi nilai ambient dari lingkungan CI atau kontainer.

Konteks jejak masuk juga berlaku untuk event. Dalam sesi Agent SDK dan -p dengan TRACEPARENT diatur, setiap catatan log event OTLP membawa nilai trace_id dan span_id yang menghubungkannya ke jejak aplikasi Anda, bahkan ketika eksporter jejak tidak dikonfigurasi, sehingga backend logging Anda dapat mengorelasikan event dengan sisa jejak.

Catatan yang dipancarkan saat interaksi aktif membawa ID span interaksi, bahkan ketika Claude Code memancarkannya di luar konteks async span, seperti dalam callback permintaan izin atau untuk catatan yang di-buffer selama startup dan diekspor nanti. Catatan yang dipancarkan tanpa span interaksi aktif membawa ID TRACEPARENT masuk secara langsung.

Hierarki span

Setiap prompt pengguna memulai span root claude_code.interaction. Panggilan API, panggilan alat, dan eksekusi hook dicatat sebagai anak-anaknya. Span alat memiliki dua span anak mereka sendiri: satu untuk waktu yang dihabiskan menunggu keputusan izin dan satu untuk eksekusi itu sendiri. Ketika alat Agent, atau alat Task warisan, memunculkan subagen, span API dan alat subagen bersarang di bawah span claude_code.tool induk.

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans

Dalam sesi Agent SDK dan claude -p, claude_code.interaction itu sendiri menjadi anak dari span pemanggil ketika TRACEPARENT diatur dalam lingkungan.

Ketika hook PreToolUse menunda panggilan alat, Claude Code menyimpan konteks jejak dari giliran yang menundanya. Ketika Anda melanjutkan sesi dan alat berjalan kembali, span alat bergabung dengan jejak giliran sebelumnya sebagai anak dari span claude_code.interaction giliran.

Atribut span

Setiap span membawa atribut standar ditambah atribut span.type yang cocok dengan namanya. Tabel di bawah mencantumkan atribut tambahan yang diatur pada setiap span. Span llm_request, tool.execution, dan hook menetapkan status OpenTelemetry ERROR ketika mereka mencatat kegagalan; span lainnya selalu berakhir dengan status UNSET.

claude_code.interaction

claude_code.llm_request

Setiap upaya percobaan ulang juga dicatat sebagai event span gen_ai.request.attempt dengan atribut attempt dan client_request_id.

claude_code.tool

tool.output span event pada claude_code.tool

Jika Anda menetapkan OTEL_LOG_TOOL_CONTENT=1, panggilan Read dan Bash dapat mencatat event span tool.output pada span claude_code.tool. Panggilan Edit dan Write mencatat satu hanya ketika Anda juga menetapkan OTEL_LOG_TOOL_DETAILS=1. Variabel itu tidak dibatasi pada kedua alat itu, jadi periksa barisnya dalam tabel konfigurasi untuk argumen yang ditambahkannya di tempat lain.

Alat MCP, WebFetch, dan WebSearch juga mencatat event ini, pada Claude Code v2.1.283 atau lebih baru.

Claude Code menulis event ini dari pengembalian sukses panggilan alat, jadi panggilan yang menimbulkan kesalahan tidak mencatat apa pun, apa pun alatnya. Di antara panggilan yang memang kembali, itu tidak mencatat event tool.output untuk:

• Panggilan ke alat apa pun selain Read, Edit, Write, Bash, WebFetch, WebSearch, dan alat MCP
• Read yang mengembalikan apa pun selain teks file, seperti gambar, PDF, atau pembacaan ulang file yang isinya belum berubah
• Panggilan Edit atau Write, kecuali Anda juga menetapkan OTEL_LOG_TOOL_DETAILS=1
• Panggilan WebFetch atau WebSearch yang Claude Code pindahkan ke latar belakang saat berjalan agar pesan yang sedang menunggu dapat mencapai Claude. Hasil yang tiba kemudian juga tidak dicatat. Untuk mengetahui kapan Claude Code memindahkan panggilan, lihat Kapan Claude Code mengirim apa yang Anda antrekan untuk terminal dan field priority untuk sesi Agent SDK

Event membawa atribut ini, masing-masing dipotong pada batas konten (60 KB secara default). Gated by menamai variabel yang atribut butuhkan di atas OTEL_LOG_TOOL_CONTENT=1, dan untuk Edit dan Write variabel itu membuka gerbang event itu sendiri daripada atribut.

Atribut tool_name span induk memberi tahu Anda alat mana yang berasal dari event. Atribut yang dipotong pada batas konten disertai dengan <attribute>_truncated dan <attribute>_original_length.

claude_code.tool.blocked_on_user

Keputusan cancelled dengan source user_abort berarti sebuah pesan yang memerlukan pengiriman segera menginterupsi giliran saat permintaan izin atau pemeriksaan auto mode masih tertunda. Misalnya, selama pemeriksaan auto mode, pengguna memiliki pesan dalam antrean dan mengirimnya segera.

claude_code.tool.execution

claude_code.hook

Span ini muncul hanya ketika tracing beta terperinci aktif, yang memerlukan ENABLE_BETA_TRACING_DETAILED=1 dan BETA_TRACING_ENDPOINT, pasangan yang juga mengubah tempat log dan jejak Anda pergi. Atur pasangan dalam shell, pengaturan pengguna, atau pengaturan terkelola; kedua variabel diabaikan dalam pengaturan proyek dan lokal. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA saja tidak menghasilkannya.

Dalam sesi CLI interaktif, tracing beta terperinci juga memerlukan organisasi Anda untuk diizinkan untuk fitur tersebut. Sesi Agent SDK dan non-interaktif -p tidak memerlukan izin.

Atribut konten di bawah tracing beta terperinci

[!NOTE]

Atribut tambahan yang membawa konten seperti new_context, system_reminders, system_prompt_preview, user_system_prompt, tool_input, dan response.model_output dipancarkan hanya ketika tracing beta terperinci aktif. Atribut-atribut ini bukan bagian dari skema span yang stabil.

Atribut-atribut ini muncul pada span di bawah, dan Gated by menamai variabel yang dibutuhkan atribut di atas tracing beta terperinci. Nilai yang lebih panjang dari batas konten (60 KB secara default) dipotong.

Di bawah tracing beta terperinci dengan OTEL_LOG_USER_PROMPTS=1, Claude Code juga memancarkan event claude_code.system_prompt yang membawa system prompt lengkap, dipotong pada batas konten. Event ini tiba pertama kali sebuah sesi mengirim setiap system prompt yang berbeda, dan lagi setelah compaction.

Header dinamis

Untuk lingkungan perusahaan yang memerlukan autentikasi dinamis, Anda dapat mengonfigurasi skrip untuk menghasilkan header secara dinamis. Header dinamis berlaku hanya untuk protokol http/protobuf dan http/json. Dengan protokol grpc, Claude Code hanya menggunakan variabel header statis, OTEL_EXPORTER_OTLP_HEADERS dan varian spesifik sinyal-nya.

Konfigurasi pengaturan

Tambahkan ke .claude/settings.json Anda, ganti jalur dengan skrip Anda sendiri:

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

Nilai dapat berupa jalur ke file yang dapat dieksekusi, termasuk jalur yang berisi spasi, atau baris perintah shell dengan argumen. Di Windows, nilai selalu berjalan melalui shell, jadi kutip jalur yang berisi spasi di dalam nilai JSON.

Persyaratan skrip

Skrip harus menampilkan JSON yang valid dengan pasangan kunci-nilai string yang mewakili header HTTP:

#!/bin/bash
# Contoh: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Jika helper gagal atau mencetak output yang tidak memenuhi persyaratan ini, ekspor gagal dan backend telemetri Anda tidak menerima apa pun dari sesi sampai helper berfungsi lagi. Claude Code melaporkan kegagalan dalam:

• Notifikasi peringatan dalam sesi interaktif, otelHeadersHelper failed; telemetry is not being exported, ditampilkan sekali per sesi ketika helper pertama kali gagal
• Output /status
• Log debug, saat berjalan dengan --debug atau setelah menjalankan /debug dalam sesi
• stderr, dalam sesi non-interaktif yang dimulai dengan -p

Perilaku penyegaran

Skrip helper header berjalan saat startup dan secara berkala setelahnya untuk mendukung penyegaran token. Secara default, skrip berjalan setiap 29 menit. Sesuaikan interval dengan variabel lingkungan CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS.

Dukungan organisasi multi-tim

Organisasi dengan beberapa tim atau departemen dapat menambahkan atribut kustom untuk membedakan antara kelompok yang berbeda menggunakan variabel lingkungan OTEL_RESOURCE_ATTRIBUTES:

# Tambahkan atribut kustom untuk identifikasi tim
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Atribut kustom ini disertakan dalam semua metrik dan event, memungkinkan Anda untuk:

• Filter metrik berdasarkan tim atau departemen
• Lacak biaya per pusat biaya
• Buat dashboard khusus tim
• Atur peringatan untuk tim tertentu

Claude Code melampirkan nilai-nilai ini sebagai atribut pada setiap titik data metrik dan catatan event, selain mengirimkannya dalam blok sumber daya OTLP. Karena sebagian besar backend metrik mengekspos atribut titik data sebagai label yang dapat dipertanyakan, Anda dapat mengelompokkan dan memfilter metrik berdasarkan kunci kustom Anda secara langsung. Kecuali untuk atribut repositori vcs.* repository attributes, kunci kustom tidak pernah menimpa atribut standar seperti user.id atau session.id: ketika kunci bertabrakan, Claude Code menyimpan nilai bawaan.

Setiap kunci kustom menjadi label pada setiap seri metrik, jadi nilai kardinalitas tinggi meningkatkan biaya penyimpanan di backend metrik Anda. Untuk mengirim atribut kustom dalam blok sumber daya saja dan menghilangkannya dari label titik data, atur OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false. Lihat Kontrol kardinalitas metrik.

[!WARNING]

Variabel lingkungan OTEL_RESOURCE_ATTRIBUTES menggunakan pasangan kunci=nilai yang dipisahkan koma dengan persyaratan pemformatan yang ketat:

• Tidak ada spasi yang diizinkan: nilai tidak dapat berisi spasi. Misalnya, user.organizationName=My Company tidak valid
• Format: harus berupa pasangan kunci=nilai yang dipisahkan koma: key1=value1,key2=value2
• Karakter yang diizinkan: hanya karakter US-ASCII yang mengecualikan karakter kontrol, spasi, tanda kutip ganda, koma, titik koma, dan garis miring terbalik
• Karakter khusus: karakter di luar rentang yang diizinkan harus dikodekan persen

Untuk nilai yang memerlukan spasi, gunakan garis bawah atau camelCase sebagai gantinya. Contoh berikut menetapkan org.name dengan setiap bentuk:

export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

Anda dapat mengkodekan persen karakter apa pun, bukan hanya yang dikecualikan. Contoh ini mengkodekan spasi dan apostrof:

export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Membungkus nilai dalam tanda kutip tidak menghindari spasi. Misalnya, org.name="My Company" menghasilkan nilai literal "My Company" dengan tanda kutip disertakan, bukan My Company.

Atribusikan telemetri ke sesi SSH Desktop

Untuk melihat di mesin jarak jauh mana sebuah sesi SSH Desktop berjalan, beri nama setiap mesin dalam atribut kustom. Metrik dan event tidak menyebutkan mesin tempat sebuah sesi berjalan.

Di setiap mesin jarak jauh, tambahkan OTEL_RESOURCE_ATTRIBUTES ke blok env yang mengaktifkan telemetri, dalam file pengaturan terkelola yang dibaca sesi. Tuliskan namanya secara eksplisit di file setiap mesin. Claude Code tidak mengekspansi nilai tersebut, sehingga host.name=$(hostname) tiba sebagai karakter-karakter itu apa adanya.

Contoh berikut menamai mesin build-7:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_RESOURCE_ATTRIBUTES": "host.name=build-7"
  }
}

Ketika tidak ada hal lain yang menetapkan variabel tersebut, host.name tiba di blok sumber daya, dalam sesi SSH Desktop dan di CLI pada mesin tersebut. Untuk tempat lain atribut kustom muncul, lihat Dukungan organisasi multi-tim.

Jika nama tersebut tidak tiba, periksa salah satu penyebab berikut:

• Anda menetapkannya di komputer yang menjalankan Desktop: Desktop tidak meneruskan nilai yang Anda tetapkan di sana ke sesi SSH
• Anda mengekspornya di /etc/profile atau file lain yang hanya dibaca oleh login shell: nama tersebut tiba ketika Anda menjalankan claude dari login shell, tetapi tidak dalam sesi SSH Desktop. Desktop tidak memulai Claude Code melalui login shell. Sebagai gantinya, tetapkan variabel tersebut di bawah env dalam file pengaturan terkelola di mesin jarak jauh.
• Sebuah nilai mengandung spasi: Claude Code kemudian tidak menyalin satu pun kunci ke event atau titik data dan tidak melaporkan error. Hapus spasi dari nilai tersebut.
• Sesuatu yang lain sudah menetapkan variabel tersebut: dalam sesi yang dimulai oleh aplikasi desktop, variabel yang sudah ditetapkan di lingkungan peluncuran diutamakan daripada file pengaturan. Log debug menyebutkan setiap variabel yang diabaikan. Ketika deployment Desktop pihak ketiga menyebutkan endpoint OTLP dalam lingkungan yang disediakannya, lingkungan tersebut membawa OTEL_RESOURCE_ATTRIBUTES milik Desktop sendiri.

Konfigurasi contoh

Atur variabel lingkungan ini sebelum menjalankan claude. Setiap skenario di bawah menunjukkan konfigurasi lengkap, dan setiap variabel dijelaskan di bawah Variabel konfigurasi umum. Untuk mengonfirmasi konfigurasi berlaku, periksa backend Anda untuk metrik claude_code.session.count setelah memulai sesi; Quick start mencakup verifikasi log saja dan apa yang harus diperiksa ketika tidak ada yang tiba.

Untuk debugging konsol dengan interval ekspor 1 detik:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

Untuk OTLP melalui gRPC:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Untuk Prometheus, yang discrape dari http://localhost:9464/metrics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

Pada lingkungan yang di-host sendiri, sesi mengikat port 9464 hanya pada kapasitas default runner satu. Pada kapasitas yang lebih tinggi, runner kembali mengekspos penghitung dan gauge sesi pada endpoint /metrics miliknya sendiri sebagai gantinya.

Untuk mengirim metrik ke beberapa eksporter:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

Untuk mengirim metrik dan log ke endpoint atau backend yang berbeda:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

Untuk mengekspor metrik saja, tanpa event atau log:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Untuk mengekspor event dan log saja, tanpa metrik:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Telemetri dari sesi cloud dan Claude Tag

Sesi cloud, termasuk sesi saluran Claude Tag, berjalan di lingkungan cloud daripada di perangkat pengguna Anda, jadi file pengaturan terkelola atau profil shell di perangkat tersebut tidak mengonfigurasi telemetri mereka. Untuk sesi di lingkungan yang dihosting Anthropic, bagian ini mencakup tempat untuk menetapkan variabel telemetri, cara membuat kolektor Anda dapat diakses dari lingkungan, dan cara membedakan sesi cloud dan Claude Tag dalam data yang diekspor.

Untuk mengekspor telemetri dari sesi tersebut, atur CLAUDE_CODE_ENABLE_TELEMETRY dan variabel OTEL_*, menggunakan kunci yang sama seperti contoh konfigurasi administrator, di salah satu dari dua tempat:

• Pengaturan yang dikelola server: tambahkan ke blok env dari pengaturan yang dikelola server organisasi Anda. Claude Code mengambil pengaturan tersebut saat startup di mana pun pengaturan yang dikelola server berlaku, yang mencakup mesin pengguna Anda dan sesi cloud selain sesi saluran Claude Tag. Sesi Claude Tag tidak menerima pengaturan yang dikelola server Anda, jadi rute ini tidak mengonfigurasinya.
• Variabel lingkungan: tambahkan ke variabel lingkungan lingkungan cloud untuk mengonfigurasi hanya sesi yang berjalan di lingkungan tersebut. Ini adalah rute yang menjangkau sesi Claude Tag.

Siapa pun yang menggunakan lingkungan dapat membaca variabelnya, jadi jangan letakkan kredensial di sana, seperti token kolektor di OTEL_EXPORTER_OTLP_HEADERS. Rahasia jaringan di lingkungan juga tidak membantu, karena ekspor telemetri Claude Code sendiri adalah salah satu dari permintaan yang tidak pernah mendapatkan rahasia tersebut. Jika kolektor Anda memerlukan kredensial, konfigurasikan seluruh ekspor melalui pengaturan terkelola server sebagai gantinya, karena ketika Anda menetapkan kredensial di sana, Claude Code menghapus variabel endpoint yang ditetapkan di luar pengaturan terkelola.

Pertahankan batasan ini dalam pikiran ketika Anda mengonfigurasi telemetri untuk sesi cloud:

• Biarkan sesi menjangkau kolektor: Claude Code mengirim ekspor melalui jaringan sesi, jadi apakah itu menjangkau host di OTEL_EXPORTER_OTLP_ENDPOINT Anda tergantung pada tingkat akses jaringan lingkungan. Jika sesi tidak dapat menjangkau domain kolektor pada tingkat yang Anda pilih, tambahkan domain ke daftar izin lingkungan, karena tidak ada pengaturan yang dikelola server yang menambahkan domain ke daftar izin jaringan lingkungan.
• Channel Claude Tag: buat perubahan allowlist dan environment variable apa pun di lingkungan bersama yang ditetapkan sebagai default organisasi Anda atau disematkan ke channel.
• Cowork dikonfigurasi secara terpisah: sesi Cowork tidak menerima pengaturan yang dikelola server, seperti yang ditunjukkan tabel cakupan permukaan, jadi blok env yang dikelola server tidak mengonfigurasi telemetri mereka.

Atribut telemetri ke sesi cloud

Secara default, metrik dan acara dari sesi cloud membawa atribut standar, termasuk session.id, ccr.session.id, dan organization.id, sehingga Anda dapat memfilter berdasarkan sesi atau organisasi tanpa konfigurasi tambahan. Nilai ccr.session.id adalah CLAUDE_CODE_REMOTE_SESSION_ID sesi. Untuk mengubahnya menjadi URL transkrip sesi, lihat Tautkan output kembali ke sesi.

Untuk membedakan sesi cloud satu sama lain, kelompokkan atau filter berdasarkan ccr.session.id, bukan session.id.

Untuk mengatribusikan telemetri secara lebih detail, gunakan opsi berikut:

• Identifikasi sesi Claude Tag: atur OTEL_METRICS_INCLUDE_ENTRYPOINT=true, seperti yang dijelaskan di bawah Kontrol kardinalitas metrik. Metrik kemudian membawa app.entrypoint, yang nilainya adalah claude-in-slack untuk sesi Claude Tag.
• Tambahkan atribut kustom: atur OTEL_RESOURCE_ATTRIBUTES di tempat yang sama di mana Anda menetapkan variabel OTEL_* lainnya untuk sesi tersebut. Jika Anda export di skrip setup lingkungan sebagai gantinya, nilainya tidak mencapai Claude Code: skrip setup adalah skrip Bash terpisah yang berjalan sebelum Claude Code diluncurkan, dan variabel yang diekspor berakhir dengannya.

Dalam sesi saluran Claude Tag, Claude bekerja sebagai identitas bersama organisasi Anda daripada sebagai anggota apa pun, jadi jangan andalkan atribut user.* untuk mengidentifikasi siapa yang menandai Claude.

Metrik dan event yang tersedia

Atribut standar

Semua metrik dan event berbagi atribut standar berikut:

Dalam sesi yang masuk ke Claude apps gateway melalui /login, CLI membubuhkan identitas yang terautentikasi pada ekspor: user.id adalah subjek IdP, user.email adalah email yang digunakan untuk masuk, dan user.groups membawa keanggotaan grup IdP sebagai string yang dipisahkan koma. Setiap ekspor juga membawa identity.source: gateway-oidc. Identitas gateway diterapkan terakhir, sehingga kunci user.* dan identity.* yang ditetapkan melalui OTEL_RESOURCE_ATTRIBUTES diabaikan pada sesi tersebut.

[!NOTE]

Event yang dicatat Claude Code sebelum developer masuk tidak membawa identitas gateway. Saat Claude Code membuka sesi dalam keadaan keluar dari gateway, misalnya setelah gateway mengakhiri proses masuk, event startup yang dicatat sebelum masuk membawa user.id anonim dan tidak ada identity.source. Event ini mencakup managed_settings_resolved, plugin_loaded, dan mcp_server_connection.

Untuk atribut identitas pada sesi Claude Desktop dan Cowork yang terhubung melalui gateway, lihat referensi telemetry gateway.

Event juga menyertakan atribut berikut. Atribut ini tidak pernah dilampirkan ke metrik karena akan menyebabkan kardinalitas yang tidak terbatas:

• prompt.id: UUID yang menghubungkan prompt pengguna dengan semua event berikutnya hingga prompt selanjutnya. Lihat Atribut korelasi event.
• workspace.host_paths: direktori workspace host yang dipilih di aplikasi desktop, sebagai array string
• workflow.run_id: pengidentifikasi run, berawalan wf_, pada event API dan tool yang dipancarkan oleh agent yang termasuk dalam run tool Workflow. Memfilter event berdasarkan satu workflow.run_id akan merekonstruksi permintaan API dan hasil tool dari run tersebut. Pengidentifikasi ini mencakup agent yang dibuat oleh skrip workflow dan agent apa pun yang pada gilirannya dibuat oleh agent tersebut, seperti pemanggilan skill. Nilainya cocok dengan pengidentifikasi run yang dilaporkan dalam hasil tool Workflow.
• workflow.name: nama workflow, yaitu meta.name dari skripnya, dipancarkan bersama workflow.run_id. Nama workflow bawaan muncul apa adanya ketika run menjalankan skrip bawaan yang tidak dimodifikasi. Nama yang dibuat pengguna, termasuk salinan skrip bawaan yang telah diedit, diganti dengan custom kecuali OTEL_LOG_TOOL_DETAILS=1 ditetapkan.
• agent_id: pengidentifikasi subagent yang memunculkan event, seperti a3f2c1b4d5e6f7a80. Event yang membawanya mencakup event API dan tool milik subagent, event assistant_response miliknya, dan subagent_completed untuk subagent yang telah selesai. Tidak ada pada event sesi utama dan event rekan tim dalam proses. agent_id span milik subagent memiliki nilai yang sama, atau menambahkan label setelah a di awal seperti pada acompact-3f2c1b4d5e6f7a80. Memerlukan Claude Code v2.1.310 atau yang lebih baru
• parent_agent_id: agent_id dari agent yang membuat atau terakhir melanjutkan subagent yang memunculkan event. Tidak ada ketika agent tersebut adalah sesi utama. Memerlukan Claude Code v2.1.310 atau yang lebih baru

Atribut repositori

Tetapkan OTEL_METRICS_INCLUDE_REPOSITORY=true untuk menandai metrik dan event dengan identitas repositori sesi, sehingga collector bersama dapat mengatribusikan penggunaan per repositori. Memerlukan Claude Code v2.1.269 atau lebih baru.

Claude Code menurunkan atribut ini sekali per sesi dari remote origin repositori. Ketika remote HTTPS dan SSH dari suatu repositori menyebutkan host dan path yang sama, seperti pada GitHub, GitLab, dan Bitbucket Cloud, keduanya menghasilkan nilai yang identik:

Nilai diubah menjadi huruf kecil, dan kredensial, query string, serta fragmen dari URL remote tidak pernah muncul di dalamnya. Atribut dihilangkan ketika sesi tidak memiliki remote origin, ketika remote tidak berbentuk URL, atau ketika satu-satunya repositori yang melingkupinya adalah direktori home Anda.

Untuk mendapatkan atribut ini dari sesi cloud, tetapkan variabel telemetri, termasuk OTEL_METRICS_INCLUDE_REPOSITORY, pada lingkungan cloud-nya. Izinkan juga domain collector Anda dalam akses jaringan lingkungan tersebut.

Kunci vcs.* yang Anda deklarasikan di OTEL_RESOURCE_ATTRIBUTES menggantikan nilai turunan untuk kunci tersebut. Jika Anda mendeklarasikan vcs.repository.url.full, Claude Code tidak pernah membaca remote dan hanya melaporkan kunci yang Anda deklarasikan.

Jika clone HTTPS dan SSH dari satu repositori melaporkan nilai yang berbeda, seperti pada instalasi self-hosted yang URL clone HTTPS-nya membawa awalan path yang tidak dimiliki URL SSH, deklarasikan vcs.repository.url.full di OTEL_RESOURCE_ATTRIBUTES bersama setiap kunci vcs.* lain yang ingin Anda laporkan. Setiap clone kemudian melaporkan identitas yang Anda deklarasikan.

Atribut ini hanya mengalir ke exporter Anda sendiri; telemetri Anthropic membuang setiap kunci vcs.*.

Metrik

Claude Code mengekspor metrik berikut. Kolom Unit menunjukkan string unit OpenTelemetry yang dilampirkan pada setiap metrik; metrik hitungan tidak membawa unit.

Ketika prometheus adalah satu-satunya exporter yang tercantum di OTEL_METRICS_EXPORTER, Claude Code menghilangkan unit USD, tokens, dan s dari metrik yang diekspor agar hasil scrape tetap dalam format teks Prometheus yang valid. Nama metrik tidak berubah, dan konfigurasi yang menggabungkan exporter, seperti otlp,prometheus, tetap mempertahankan unit.

Detail metrik

Setiap metrik menyertakan atribut standar yang tercantum di atas. Metrik dengan atribut tambahan yang spesifik konteks dicatat di bawah ini.

Penghitung sesi

Bertambah pada awal setiap sesi.

Atribut:

• Semua atribut standar
• start_type: Cara sesi dimulai. Salah satu dari "fresh", "resume", "continue", atau "agents_view". Nilai "agents_view" mengidentifikasi proses dasbor claude agents, yaitu UI lokal yang diluncurkan pengguna, bukan sesi percakapan. Filter berdasarkan nilai ini untuk memisahkan peluncuran proses UI dari sesi percakapan di dasbor Anda.

Penghitung baris kode

Bertambah ketika kode ditambahkan atau dihapus.

Atribut:

• Semua atribut standar
• type: ("added", "removed")
• model: Pengidentifikasi model untuk model yang membuat perubahan (misalnya, "claude-sonnet-5")

Penghitung pull request

Bertambah ketika Claude Code membuat pull request atau merge request melalui perintah shell atau tool MCP.

Atribut:

• Semua atribut standar

Penghitung commit

Bertambah ketika membuat commit git melalui Claude Code.

Atribut:

• Semua atribut standar

Penghitung biaya

Bertambah setelah setiap permintaan API.

Atribut agent.name, skill.name, plugin.name, mcp_server.name, dan mcp_tool.name masing-masing menyamarkan sebagian nama menjadi placeholder "custom" atau "third-party" secara default. Jika Anda menetapkan OTEL_LOG_TOOL_DETAILS=1, atribut tersebut membawa nama sebenarnya. Sebelum v2.1.273, penghitung biaya dan token serta event api_request, api_error, dan api_refusal membawa nilai yang disamarkan meskipun OTEL_LOG_TOOL_DETAILS=1 ditetapkan.

Atribut:

• Semua atribut standar
• model: Pengidentifikasi model (misalnya, "claude-sonnet-5")
• query_source: Kategori subsistem yang mengeluarkan permintaan. Salah satu dari "main", "subagent", atau "auxiliary"
• speed: "fast" ketika permintaan menggunakan fast mode. Tidak ada jika sebaliknya
• effort: Tingkat effort yang diterapkan pada permintaan: "low", "medium", "high", "xhigh", atau "max". Tidak ada ketika Claude Code tidak mengirimkan tingkat effort, misalnya pada model yang tidak mendukung effort.
• agent.name: Jenis subagent yang mengeluarkan permintaan. Nama agent bawaan dan agent dari plugin marketplace resmi muncul apa adanya. Nama agent lain yang ditentukan pengguna diganti dengan "custom". Tidak ada ketika permintaan tidak dikeluarkan oleh jenis subagent bernama.
• skill.name: Skill yang aktif untuk permintaan, ditetapkan oleh tool Skill atau perintah /, atau diwarisi oleh subagent yang dimunculkan. Nama skill bawaan, yang dibundel, yang ditentukan pengguna, dan dari plugin marketplace resmi muncul apa adanya. Nama skill plugin pihak ketiga diganti dengan "third-party". Tidak ada ketika tidak ada skill yang aktif.
• plugin.name: Plugin pemilik ketika skill atau subagent yang aktif disediakan oleh plugin. Nama plugin marketplace resmi muncul apa adanya. Nama plugin pihak ketiga diganti dengan "third-party". Tidak ada ketika baik skill maupun subagent tidak memiliki plugin pemilik.
• marketplace.name: Marketplace tempat plugin pemilik diinstal. Hanya dipancarkan untuk plugin marketplace resmi, bahkan ketika OTEL_LOG_TOOL_DETAILS=1 ditetapkan. Tidak ada jika sebaliknya.
• mcp_server.name: Server MCP yang hasil tool-nya dikonsumsi oleh permintaan ini. Nama server bawaan, yang diproksikan claude.ai, dan dari registri resmi muncul apa adanya. Nama server yang dikonfigurasi pengguna diganti dengan "custom". Tidak ada ketika permintaan tidak mengonsumsi hasil tool MCP. Sebelum v2.1.222, Claude Code menetapkan atribut ini pada setiap permintaan setelah panggilan tool MCP, tidak hanya pada permintaan yang mengonsumsi hasil tool, sehingga dasbor yang mengagregasinya menunjukkan penurunan setelah Anda melakukan upgrade.
• mcp_tool.name: Tool MCP yang hasilnya dikonsumsi oleh permintaan ini, dengan perilaku penyamaran dan versi yang sama seperti mcp_server.name. Tidak ada ketika permintaan tidak mengonsumsi hasil tool MCP.

Penghitung token

Bertambah setelah setiap permintaan API.

Atribut:

• Semua atribut standar
• type: ("input", "output", "cacheRead", "cacheCreation"). Jenis "input" tidak mencakup token yang dibaca dari atau ditulis ke cache prompt, yang dihitung di bawah "cacheRead" dan "cacheCreation". Jenis "cacheCreation" menghitung penulisan cache dengan masa berlaku cache lima menit dan satu jam secara bersamaan.
• model: Pengidentifikasi model (misalnya, "claude-sonnet-5")
• query_source: Kategori subsistem yang mengeluarkan permintaan. Salah satu dari "main", "subagent", atau "auxiliary"
• speed: "fast" ketika permintaan menggunakan fast mode. Tidak ada jika sebaliknya
• effort: Tingkat effort yang diterapkan pada permintaan. Lihat Penghitung biaya untuk detailnya.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribusi skill, plugin, agent, dan MCP untuk permintaan. Lihat Penghitung biaya untuk definisi dan perilaku penyamaran.

Penghitung keputusan tool pengeditan kode

Bertambah ketika pengguna menerima atau menolak penggunaan tool Edit, Write, atau NotebookEdit.

Atribut:

• Semua atribut standar
• tool_name: Nama tool ("Edit", "Write", "NotebookEdit")
• decision: Keputusan pengguna ("accept", "reject")
• source: Asal keputusan. Salah satu dari "config", "hook", "user_permanent", "user_temporary", "user_abort", atau "user_reject". Lihat Event keputusan tool untuk arti setiap nilai.
• language: Bahasa pemrograman dari file yang diedit, seperti "TypeScript", "Python", "JavaScript", atau "Markdown". Mengembalikan "unknown" untuk ekstensi file yang tidak dikenali.

Penghitung waktu aktif

Melacak waktu aktual yang dihabiskan untuk secara aktif menggunakan Claude Code, tidak termasuk waktu diam. Metrik ini bertambah selama interaksi pengguna, seperti mengetik dan membaca respons, dan selama pemrosesan CLI, seperti eksekusi tool dan pembuatan respons AI.

Atribut:

• Semua atribut standar
• type: "user" untuk interaksi keyboard, "cli" untuk eksekusi tool dan respons AI

Event

Claude Code mengekspor event berikut melalui log/event OpenTelemetry (ketika OTEL_LOGS_EXPORTER dikonfigurasi):

Atribut korelasi event

Ketika pengguna mengirimkan prompt, Claude Code dapat melakukan beberapa panggilan API dan menjalankan beberapa tool. Atribut prompt.id memungkinkan Anda mengaitkan semua event tersebut kembali ke satu prompt yang memicunya.

Untuk melacak semua aktivitas yang dipicu oleh satu prompt, filter event Anda berdasarkan nilai prompt.id tertentu. Ini akan mengembalikan event user_prompt, event api_request apa pun, dan event tool_result apa pun yang terjadi saat memproses prompt tersebut.

event.sequence dimulai dari 0 setiap kali proses Claude Code dimulai dan bertambah selama masa hidup proses tersebut. Penghitung ini terus berjalan melewati /clear, yang menetapkan session.id baru. Jika Anda melanjutkan sesi tanpa fork, sesi tetap mempertahankan session.id-nya tetapi mengambil nilai event.sequence dari proses yang melanjutkannya, sehingga dalam satu sesi, event yang lebih baru dapat membawa nilai yang lebih rendah daripada event sebelumnya, atau mengulang nilai yang sama. Untuk mengurutkan event suatu sesi, urutkan berdasarkan event.timestamp dan gunakan event.sequence untuk mengurutkan event yang memiliki timestamp yang sama.

Untuk rekonstruksi tingkat pesan, setiap kelas event membawa kunci yang cocok dengan sebuah field dalam transkrip sesi. Format entri transkrip bersifat internal bagi Claude Code dan berubah antar versi, sehingga pipeline yang melakukan join pada field ini dapat rusak pada rilis mana pun; perlakukan join tersebut sebagai spesifik versi, bukan kontrak yang stabil:

• message.uuid pada user_prompt, assistant_response, dan api_response_body
• request_id pada event API, disimpan sebagai requestId pada entri asisten dalam transkrip
• tool_use_id pada event tool_result dan tool_decision, serta pada event safety_event kecuali yang untuk akhir giliran

Event prompt pengguna

Dicatat ketika prompt dikirimkan, termasuk pada giliran yang dimulai Claude Code dengan sendirinya.

Nama Event: claude_code.user_prompt

Atribut:

• Semua atribut standar
• event.name: "user_prompt"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• prompt_length: Panjang prompt
• prompt: Konten prompt. Disamarkan secara default. Tetapkan OTEL_LOG_USER_PROMPTS=1 untuk menyertakannya
• prompt_text: Nilai yang sama dengan prompt, disamarkan dengan kondisi yang sama. Backend yang menyimpan nama atribut bertitik sebagai objek bersarang membaca prompt.id sebagai id di dalam objek bernama prompt dan dapat kehilangan string prompt. Baca prompt_text di sana sebagai gantinya. Memerlukan Claude Code v2.1.287 atau lebih baru
• message.uuid: UUID pesan pengguna yang dihasilkan, cocok dengan entri transkrip yang disimpan. Tidak ada pada dispatch perintah, yang dapat menghasilkan nol atau banyak pesan.
• command_name: Nama perintah ketika prompt memanggil perintah. Nama perintah bawaan dan yang dibundel seperti compact atau debug dipancarkan apa adanya; alias seperti reset dipancarkan sebagaimana diketik, bukan nama kanonisnya. Nama perintah kustom, plugin, dan MCP diringkas menjadi custom atau mcp kecuali OTEL_LOG_TOOL_DETAILS=1 ditetapkan
• command_source: Asal perintah jika ada: builtin, custom, atau mcp. Perintah yang disediakan plugin dilaporkan sebagai custom

Event respons asisten

Dicatat setelah setiap permintaan API yang mengembalikan konten teks dari model. Hanya blok teks respons yang disertakan; thinking block dan blok tool-use dikecualikan.

Nama Event: claude_code.assistant_response

Atribut:

• Semua atribut standar
• event.name: "assistant_response"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• response_length: Panjang teks respons dalam karakter
• response: Teks respons, dipotong pada batas konten (60 KB secara default). Disamarkan menjadi <REDACTED> secara default. Tetapkan OTEL_LOG_ASSISTANT_RESPONSES=1 untuk menyertakannya. Ketika OTEL_LOG_ASSISTANT_RESPONSES tidak ditetapkan, OTEL_LOG_USER_PROMPTS yang mengendalikannya, jadi tetapkan OTEL_LOG_ASSISTANT_RESPONSES=0 agar respons tetap disamarkan saat logging prompt aktif
• model: Pengidentifikasi model (misalnya, "claude-sonnet-5")
• request_id: ID permintaan API, dijelaskan di bawah Atribut korelasi event
• message.uuid: UUID entri transkrip terakhir dari respons. Respons API disimpan sebagai satu entri transkrip per blok konten; ini adalah yang terakhir, yang menjadi rantai parentUuid giliran berikutnya.
• query_source: Subsistem yang mengeluarkan permintaan, seperti "repl_main_thread", "compact", atau nama subagent

Event hasil tool

Dicatat ketika tool selesai dieksekusi. Tidak dipancarkan jika panggilan tool ditolak; lihat Event keputusan tool untuk penolakan.

Nama Event: claude_code.tool_result

Atribut:

• Semua atribut standar
• event.name: "tool_result"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• tool_name: Nama tool
• tool_use_id: Pengidentifikasi unik untuk pemanggilan tool ini. Cocok dengan tool_use_id yang diteruskan ke hook, memungkinkan korelasi antara event OTel dan data yang ditangkap hook.
• request_id: request_id dari respons API yang memuat panggilan tool ini, sehingga Anda dapat melakukan join panggilan tersebut dengan event API dari respons itu. Tidak ada ketika respons tersebut tidak memiliki ID permintaan, atau ketika tidak ada respons API yang memuat panggilan tersebut. Memerlukan Claude Code v2.1.310 atau yang lebih baru
• success: "true" atau "false"
• duration_ms: Waktu eksekusi dalam milidetik
• error_type: String kategori error ketika tool gagal, seperti "Error:ENOENT" atau "ShellError"
• error (ketika OTEL_LOG_TOOL_DETAILS=1): Pesan error lengkap ketika tool gagal
• decision_type: Selalu "accept", karena event ini hanya dipancarkan setelah tool berjalan. Panggilan yang ditolak tidak menghasilkan hasil tool
• decision_source: Asal keputusan izin. Salah satu dari "config", "hook", "user_permanent", atau "user_temporary". Lihat Event keputusan tool untuk arti setiap nilai. Sumber khusus penolakan "user_abort" dan "user_reject" tidak pernah muncul pada event ini.
• tool_input_size_bytes: Ukuran input tool yang diserialisasi JSON dalam byte
• tool_result_size_bytes: Ukuran hasil tool dalam byte
• mcp_server_scope: Pengidentifikasi cakupan server MCP (untuk tool MCP)
• vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type (ketika OTEL_LOG_TOOL_DETAILS=1): identitas commit dari git commit yang berhasil dijalankan oleh tool Bash atau PowerShell. vcs.ref.head.revision adalah SHA commit, vcs.ref.head.name adalah branch tempat commit dibuat, dan vcs.ref.head.type adalah branch. Nama dan jenis dihilangkan ketika commit dibuat pada detached HEAD. Memerlukan Claude Code v2.1.269 atau lebih baru
• tool_parameters (ketika OTEL_LOG_TOOL_DETAILS=1): String JSON yang berisi parameter spesifik tool. Untuk server bawaan Claude Desktop, dalam sesi yang dimiliki Claude Desktop, pasangan mcp_server_name/mcp_tool_name disertakan bahkan ketika flag dimatikan, pengecualian yang sama yang ditulis host seperti pada Event keputusan tool. Parameter bervariasi menurut tool:
  • Untuk tool Bash: mencakup bash_command, full_command, timeout, description, dan dangerouslyDisableSandbox, ditambah git_commit_id dan git_branch ketika perintah git commit berhasil. git_commit_id adalah SHA commit lengkap ketika commit tersebut merupakan HEAD dari direktori kerja sesi, dan SHA singkat git jika tidak. git_branch adalah branch tempat commit dibuat, dihilangkan pada detached HEAD
  • Untuk tool Bash workspace aplikasi desktop, yang juga melaporkan tool_name sebagai Bash: hanya mencakup bash_command, full_command, dan timeout
  • Untuk tool MCP: mencakup mcp_server_name, mcp_tool_name
  • Untuk tool Skill: mencakup skill_name
  • Untuk tool Agent atau tool Task lama: mencakup subagent_type
• tool_input (ketika OTEL_LOG_TOOL_DETAILS=1): Argumen tool yang diserialisasi JSON. Nilai individual yang lebih dari 512 karakter dipotong, dan payload lengkap dibatasi hingga ~4 K karakter. Berlaku untuk semua tool termasuk tool MCP.

Event permintaan API

Dicatat untuk setiap permintaan API ke Claude.

Nama Event: claude_code.api_request

Atribut:

• Semua atribut standar
• event.name: "api_request"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• model: Model yang digunakan (misalnya, "claude-sonnet-5")
• cost_usd: Perkiraan biaya dalam USD
• cost_usd_micros: Perkiraan biaya dalam sepersejuta dolar AS, dipancarkan sebagai bilangan bulat
• duration_ms: Durasi permintaan dalam milidetik
• input_tokens: Jumlah token input, tidak termasuk token yang dibaca dari atau ditulis ke cache prompt
• output_tokens: Jumlah token output
• cache_read_tokens: Jumlah token yang dibaca dari cache
• cache_creation_tokens: Jumlah token yang digunakan untuk pembuatan cache
• cache_creation_5m_tokens, cache_creation_1h_tokens: jumlah token yang dilaporkan respons API sebagai ditulis ke cache dengan masa berlaku cache lima menit dan jumlah yang ditulis dengan masa berlaku satu jam. Keduanya bernilai 0 jika respons API tidak melaporkannya, bahkan saat cache_creation_tokens di atas nol. Memerlukan Claude Code v2.1.300 atau lebih baru
• request_id: ID permintaan API, seperti "req_011...", dijelaskan di bawah Atribut korelasi event.
• client_request_id: UUID yang dibuat klien dan dikirim sebagai header permintaan x-client-request-id; lihat tabel atribut korelasi event untuk kapan atribut ini ada
• speed: "fast" atau "normal", menunjukkan apakah fast mode aktif
• query_source: Subsistem yang mengeluarkan permintaan, seperti "repl_main_thread", "compact", atau nama subagent
• effort: Tingkat effort yang diterapkan pada permintaan: "low", "medium", "high", "xhigh", atau "max". Tidak ada ketika Claude Code tidak mengirimkan tingkat effort, misalnya pada model yang tidak mendukung effort.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribusi skill, plugin, agent, dan MCP untuk permintaan. Lihat Penghitung biaya untuk definisi dan perilaku penyamaran.

Event error API

Dicatat ketika permintaan API ke Claude gagal.

Nama Event: claude_code.api_error

Atribut:

• Semua atribut standar
• event.name: "api_error"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• model: Model yang digunakan (misalnya, "claude-sonnet-5")
• error: Pesan error
• status_code: Kode status HTTP sebagai angka. Tidak ada untuk error non-HTTP seperti kegagalan koneksi.
• duration_ms: Durasi permintaan dalam milidetik
• attempt: Jumlah percobaan yang dilakukan, termasuk permintaan awal. Mendeteksi habisnya retry menjelaskan kapan penghitungan dimulai kembali
• request_id: ID permintaan API, seperti "req_011...", dijelaskan di bawah Atribut korelasi event.
• client_request_id: UUID yang dibuat klien dan dikirim sebagai header permintaan x-client-request-id. Tersedia bahkan ketika kegagalan seperti timeout atau error koneksi tidak pernah menghasilkan request_id server; lihat tabel atribut korelasi event untuk kapan atribut ini ada.
• speed: "fast" atau "normal", menunjukkan apakah fast mode aktif
• query_source: Subsistem yang mengeluarkan permintaan, seperti "repl_main_thread", "compact", atau nama subagent
• effort: Tingkat effort yang diterapkan pada permintaan. Tidak ada ketika Claude Code tidak mengirimkan tingkat effort, misalnya pada model yang tidak mendukung effort.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribusi skill, plugin, agent, dan MCP untuk permintaan. Lihat Penghitung biaya untuk definisi dan perilaku penyamaran.

Event penolakan API

Dicatat ketika permintaan API mengembalikan stop_reason: "refusal". Penolakan datang pada stream respons yang berhasil, bukan sebagai error HTTP, sehingga event api_error tidak terpicu untuknya. Event ini memungkinkan Anda melacak frekuensi penolakan dan mengelompokkan penolakan berdasarkan atribut yang sama dengan api_request dan api_error.

Nama Event: claude_code.api_refusal

Atribut:

• Semua atribut standar
• event.name: "api_refusal"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• model: Pengidentifikasi model dari permintaan
• request_id: ID permintaan API, seperti "req_011...", dijelaskan di bawah Atribut korelasi event.
• query_source: Subsistem yang mengeluarkan permintaan, seperti "repl_main_thread", "compact", atau nama subagent. Lihat api_request untuk definisinya.
• speed: Either "fast" ketika Fast mode aktif, atau "normal"
• attempt: Nomor percobaan retry. Percobaan pertama adalah 1.
• effort: Tingkat effort yang diterapkan pada permintaan. Tidak ada ketika Claude Code tidak mengirimkan tingkat effort, misalnya pada model yang tidak mendukung effort.
• server_fallback_hop: true ketika fallback model sisi server API telah mencoba ulang penolakan ini pada model lain, sehingga pengguna tidak melihat penolakan khusus ini. false ketika permintaan berakhir dengan penolakan. Satu giliran dapat memancarkan event hop true dan kemudian event akhir false ketika model fallback juga menolak.
• has_category: true ketika respons API membawa stop_details.category berupa "cyber", "bio", "frontier_llm", atau "reasoning_extraction". false ketika respons tidak membawa kategori atau membawa nilai di luar kumpulan tersebut. Tidak ada ketika server_fallback_hop adalah true, karena blok hop tidak membawa stop_details.
• has_explanation: true ketika respons API membawa stop_details.explanation, jika tidak false. Tidak ada ketika server_fallback_hop adalah true.
• category: Nilai stop_details.category dari respons API. Salah satu dari "cyber", "bio", "frontier_llm", atau "reasoning_extraction". Hanya ada ketika OTEL_LOG_TOOL_DETAILS=1 ditetapkan dan has_category adalah true.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribusi skill, plugin, agent, dan MCP untuk permintaan. Lihat Penghitung biaya untuk definisi dan perilaku penyamaran.

Event body permintaan API

Dicatat untuk setiap percobaan permintaan API ketika OTEL_LOG_RAW_API_BODIES ditetapkan. Satu event dipancarkan per percobaan, sehingga retry dengan parameter yang disesuaikan masing-masing menghasilkan event-nya sendiri.

Nama Event: claude_code.api_request_body

Atribut:

• Semua atribut standar
• event.name: "api_request_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• body: Parameter permintaan Messages API yang diserialisasi JSON, seperti system prompt, pesan, dan tool, dipotong pada batas konten (60 KB secara default). Konten extended thinking pada giliran asisten sebelumnya disamarkan. Hanya dipancarkan dalam mode inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Path absolut ke file <dir>/<uuid>.request.json yang berisi body yang tidak dipotong. Hanya dipancarkan dalam mode file (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Panjang body yang tidak dipotong. Byte UTF-8 ketika OTEL_LOG_RAW_API_BODIES=file:<dir>, atau unit kode UTF-16 ketika =1
• body_truncated: "true" ketika terjadi pemotongan inline. Tidak ada dalam mode file dan ketika tidak terjadi pemotongan.
• model: Pengidentifikasi model dari parameter permintaan
• query_source: Subsistem yang mengeluarkan permintaan (misalnya, "compact")
• request_body_id: UUID yang mengidentifikasi body permintaan dari percobaan ini. Event api_response_body untuk percobaan yang berhasil membawa nilai yang sama, sehingga Anda dapat memasangkan respons dengan permintaan persis yang menghasilkannya. Memerlukan Claude Code v2.1.274 atau lebih baru

Event body respons API

Dicatat untuk setiap respons API yang berhasil ketika OTEL_LOG_RAW_API_BODIES ditetapkan.

Dalam mode file (OTEL_LOG_RAW_API_BODIES=file:<dir>), Claude Code juga menambahkan satu baris JSON ke <dir>/index.jsonl untuk setiap respons yang berhasil, dengan field timestamp, session_id, query_source, model, request_id, message_id, message_uuid, request_file, dan response_file. Baca file ini untuk menemukan file permintaan dan respons di balik pesan transkrip tertentu tanpa melakukan query ke backend telemetri Anda. File indeks memerlukan Claude Code v2.1.274 atau lebih baru.

Nama Event: claude_code.api_response_body

Atribut:

• Semua atribut standar
• event.name: "api_response_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• body: Respons Messages API yang diserialisasi JSON, termasuk id, blok konten, penggunaan, dan alasan berhenti, dipotong pada batas konten (60 KB secara default). Konten extended thinking disamarkan. Hanya dipancarkan dalam mode inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Path absolut ke file <dir>/<request_id>.response.json yang berisi body yang tidak dipotong. Hanya dipancarkan dalam mode file (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Panjang body yang tidak dipotong. Byte UTF-8 ketika OTEL_LOG_RAW_API_BODIES=file:<dir>, atau unit kode UTF-16 ketika =1
• body_truncated: "true" ketika terjadi pemotongan inline. Tidak ada dalam mode file dan ketika tidak terjadi pemotongan.
• model: Pengidentifikasi model
• query_source: Subsistem yang mengeluarkan permintaan
• request_id: ID permintaan API, seperti "req_011...", dijelaskan di bawah Atribut korelasi event.
• request_body_id: request_body_id dari event api_request_body yang dijawab oleh respons ini. Memerlukan Claude Code v2.1.274 atau lebih baru
• message.id: ID pesan yang ditetapkan API untuk respons, yaitu field id dari body respons. Memerlukan Claude Code v2.1.274 atau lebih baru
• message.uuid: UUID entri transkrip terakhir dari respons. Bersama dengan request_body_id, atribut ini menautkan pesan transkrip ke body permintaan dan respons di baliknya. Memerlukan Claude Code v2.1.274 atau lebih baru

Event keputusan tool

Dicatat ketika keputusan izin tool dibuat (terima/tolak).

Nama Event: claude_code.tool_decision

Atribut:

• Semua atribut standar

• event.name: "tool_decision"

• event.timestamp: Timestamp ISO 8601

• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event

• tool_name: Nama tool (misalnya, "Read", "Edit", "Write", "NotebookEdit")

• tool_use_id: Pengidentifikasi unik untuk pemanggilan tool ini. Cocok dengan tool_use_id yang diteruskan ke hook, memungkinkan korelasi antara event OTel dan data yang ditangkap hook.

• request_id: request_id dari respons API yang memuat panggilan tool ini, sehingga Anda dapat melakukan join panggilan tersebut dengan event API dari respons itu. Tidak ada ketika respons tersebut tidak memiliki ID permintaan, atau ketika tidak ada respons API yang memuat panggilan tersebut. Memerlukan Claude Code v2.1.310 atau yang lebih baru

• decision: Either "accept" atau "reject"

• tool_source: Selalu ada. Asal-usul tool, sebagai kumpulan tertutup nilai yang ditulis CLI:

  • "builtin": tool milik CLI sendiri
  • "mcp": server MCP secara umum
  • "sdk_host_builtin_mcp": server dalam proses yang dibangun ke dalam Claude Desktop itu sendiri, dalam sesi yang dimiliki Claude Desktop. Claude Desktop memiliki sesi yang dimulainya dari salah satu entrypoint-nya sendiri, claude-desktop, claude-desktop-3p, atau local-agent, ketika sesi tersebut bukan anak bersarang; sesi bersarang, termasuk sesi yang dimunculkan oleh Claude Code sendiri, melaporkan server ini sebagai "mcp"

• source: Asal keputusan:

  • "config": Diputuskan secara otomatis tanpa meminta, oleh salah satu sumber berikut:

    • Pengaturan proyek
    • Aturan allow atau deny dalam pengaturan pribadi pengguna
    • Kebijakan terkelola enterprise
    • Flag --allowedTools atau --disallowedTools
    • Mode izin yang aktif
    • Pengklasifikasi auto mode, yang verdict-nya dicatat oleh event yang sama di classifier_verdict
    • Pemberian akses untuk sisa sesi, yang diberikan pada permintaan izin sebelumnya dalam sesi CLI interaktif yang sama
    • Tool yang secara inheren aman

    Nilai source tidak menunjukkan sumber mana yang cocok. Untuk menemukan sumber mana yang menolak suatu panggilan, cari Event safety dengan tool_use_id yang sama dan baca atribut category dan rule_source-nya. Beberapa panggilan yang ditolak tidak memiliki event safety.

    Claude Code juga melaporkan "config" ketika permintaan izin itu sendiri gagal. Misalnya, permintaan tersebut gagal ketika callback canUseTool dari Agent SDK atau tool --permission-prompt-tool mengembalikan hasil yang tidak valid, atau ketika stream input ditutup saat permintaan masih tertunda.

  • "hook": Hook PreToolUse atau PermissionRequest mengembalikan keputusan.

  • "user_permanent": Dipancarkan ketika pengguna memilih "Yes, and don't ask again for ..." pada permintaan izin, yang menyimpan aturan izinkan ke pengaturan pribadinya. Di CLI interaktif, ini hanya dipancarkan untuk pilihan itu sendiri; panggilan berikutnya yang cocok dengan aturan yang disimpan memancarkan "config". Dalam sesi Agent SDK atau sesi -p non-interaktif, baik pilihan awal maupun kecocokan aturan berikutnya memancarkan "user_permanent". Diperlakukan sebagai penerimaan.

  • "user_temporary": Dipancarkan ketika pengguna memilih "Yes" pada permintaan izin untuk persetujuan satu kali, atau memilih opsi yang memberikan akses untuk sisa sesi pada permintaan izin pengeditan atau pembacaan file. Di CLI interaktif, ini hanya dipancarkan untuk pilihan itu sendiri; panggilan berikutnya yang diizinkan oleh pemberian izin berlingkup sesi tersebut memancarkan "config". Dalam sesi Agent SDK atau sesi -p non-interaktif, baik pilihan maupun kecocokan berikutnya memancarkan "user_temporary". Diperlakukan sebagai penerimaan.

  • "user_abort": Dipancarkan ketika pengguna menutup permintaan izin tanpa menjawab. Dalam sesi Agent SDK dan sesi -p non-interaktif, ini termasuk menginterupsi giliran saat permintaan izin canUseTool atau --permission-prompt-tool masih tertunda. Diperlakukan sebagai penolakan.

  • "user_reject": Dipancarkan ketika pengguna memilih "No" saat diminta. Di CLI interaktif, ini hanya dipancarkan untuk pilihan itu sendiri; panggilan yang cocok dengan aturan tolak dalam pengaturan pribadi pengguna memancarkan "config". Dalam sesi Agent SDK atau sesi -p non-interaktif, panggilan yang cocok dengan aturan tolak dalam pengaturan pribadi memancarkan "user_reject". Diperlakukan sebagai penolakan.

• classifier_verdict: Verdict pengklasifikasi auto mode untuk panggilan, atau alasan Claude Code menolak panggilan ketika tidak ada verdict yang datang. Memerlukan Claude Code v2.1.301 atau lebih baru

  • "allow": pengklasifikasi menyetujui panggilan
  • "block": pengklasifikasi memblokir panggilan. Pemeriksaan pengklasifikasi yang gagal di tengah jalan juga dapat berakhir sebagai "block", sehingga gangguan parsial pengklasifikasi dapat muncul sebagai lebih banyak pemblokiran, bukan sebagai "unavailable"
  • "no_verdict": pemeriksaan berjalan tetapi tidak memberikan verdict yang dapat digunakan, sehingga Claude Code menolak panggilan. Penolakan tersebut tidak berarti pengklasifikasi menganggap panggilan tidak aman
  • "unavailable": permintaan ke pengklasifikasi gagal, misalnya karena rate limit, timeout, atau error koneksi, sehingga Claude Code menolak panggilan. Dengan peninjauan pengklasifikasi sisi server, nilai ini juga menandai panggilan yang ditolak karena server tidak mengembalikan verdict keamanan

  Atribut ini juga muncul pada panggilan plan mode ketika pengklasifikasi meninjau perintah dalam plan mode. Atribut ini tidak ada dalam kasus berikut:

  • Aturan izin allow atau deny memutuskan panggilan
  • Claude Code menyetujui panggilan dalam auto mode tanpa bertanya kepada pengklasifikasi
  • Pengguna menjawab permintaan izin yang ditampilkan Claude Code setelah pemblokiran berulang
  • Dalam run -p tanpa --permission-prompt-tool, Claude Code menolak panggilan setelah pemblokiran berulang karena tidak ada yang menjawab permintaan izin. Event tersebut melaporkan decision sebagai "reject" dan source sebagai "config"

• classifier_category (ketika OTEL_LOG_TOOL_DETAILS=1): Nama aturan bawaan yang disebut pengklasifikasi ketika memblokir panggilan, dalam huruf kecil dengan garis bawah, seperti "data_exfiltration" untuk aturan Data Exfiltration. Memerlukan Claude Code v2.1.301 atau yang lebih baru. Atribut ini ada ketika kedua kondisi berikut terpenuhi:

  • classifier_verdict bernilai "block"
  • Pengklasifikasi menyebut tepat satu aturan, dan aturan tersebut adalah aturan bawaan, bukan aturan yang Anda tulis

  Sebelum v2.1.302, atribut ini juga tidak ada pada blokir apa pun yang diputuskan oleh tinjauan pengklasifikasi sisi server.

• permission_mode: Mode izin yang aktif ketika pemeriksaan izin panggilan ini dimulai: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk", atau "auto". Mode manual muncul sebagai "default". Panggilan subagent melaporkan mode izin subagent, bukan mode izin sesi. Memerlukan Claude Code v2.1.301 atau lebih baru

• tool_parameters (ketika OTEL_LOG_TOOL_DETAILS=1): String JSON yang berisi parameter spesifik tool. Bentuknya sama dengan Event hasil tool, tanpa field pasca-eksekusi seperti git_commit_id. Nilai dapat berbeda dari tool_result untuk panggilan yang diterima jika keputusan izin menulis ulang input tool melalui updatedInput. Gunakan atribut ini untuk melihat perintah mana yang ditolak ketika decision adalah "reject".

  • Untuk tool "sdk_host_builtin_mcp": mcp_server_name dan mcp_tool_name disertakan bahkan ketika OTEL_LOG_TOOL_DETAILS dimatikan, karena aplikasi host yang mendefinisikan nama-nama ini; tanpanya, panggilan yang ditolak ke salah satu server bawaan ini tidak dapat diatribusikan pada stream default. Untuk server MCP yang dikonfigurasi pengguna, tool_name event selalu berupa literal "mcp_tool", dan nama server serta tool hanya muncul di tool_parameters dengan flag aktif; konten argumen memerlukan flag di mana pun.
  • Untuk tool Bash: mencakup bash_command, full_command, timeout, description, dangerouslyDisableSandbox. Tool bash workspace aplikasi desktop juga melaporkan tool_name sebagai Bash, tetapi hanya mencakup bash_command, full_command, dan timeout
  • Untuk tool MCP: mencakup mcp_server_name, mcp_tool_name
  • Untuk tool Skill: mencakup skill_name
  • Untuk tool Agent atau tool Task lama: mencakup subagent_type

Jika Anda menurunkan OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT milik SDK OpenTelemetry di bawah jumlah atribut pada event tool_decision, SDK membuang atribut yang ditetapkan terakhir oleh Claude Code. SDK membuang atribut ini sebelum atribut lain, dalam urutan berikut, melewati atribut yang tidak dibawa event:

1. parent_agent_id
2. agent_id
3. request_id
4. permission_mode
5. classifier_category
6. classifier_verdict

permission_mode, classifier_category, dan classifier_verdict dibuang dalam urutan ini pada Claude Code v2.1.302 atau yang lebih baru. parent_agent_id, agent_id, dan request_id memerlukan v2.1.310 atau yang lebih baru.

Event safety

Dicatat saat suatu pemeriksaan menolak panggilan tool atau mengharuskan permintaan izin, kecuali untuk panggilan tanpa event safety. Juga dicatat saat proxy jaringan sandbox menolak koneksi atau permintaan, dan saat hook memblokir hasil. Memerlukan Claude Code v2.1.307 atau lebih baru.

Event ini diekspor bersama event lainnya dan tidak memiliki pengaturan tersendiri. Atribut milik event ini sendiri tidak memuat teks perintah, path file, nama host, atau nama server dan tool MCP. Record ini juga memuat atribut standar yang dimiliki setiap event, yang dapat mencakup workspace.host_paths dan atribut repositori. Untuk melihat perintah atau tool MCP di balik suatu event, tetapkan OTEL_LOG_TOOL_DETAILS=1 dan baca tool_parameters pada event tool_decision yang cocok.

Nama Event: claude_code.safety_event

Atribut:

• Semua atribut standar
• event.name: "safety_event"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• category: Pemeriksaan atau hasilnya, berupa nilai kategori
• decision: "accept", "reject", atau "sent_back" saat hook memblokir hasil atau akhir giliran
• decision_source: Siapa atau apa yang memutuskan, berupa nilai source dari tool_decision atau "other"
• reason_code: Alasan pemeriksaan, seperti "rule:policySettings", "mode:dontAsk", "hook:PreToolUse", "classifier:auto-mode", "bashMiss:too-complex", atau "unknown"
• reason_type: Jenis alasan pemeriksaan, seperti "rule", "subcommandResults", "mode", "hook", "classifier", atau "asyncAgent"
• rule_source: Sumber pengaturan dari aturan yang terlibat, seperti "policySettings", "userSettings", "projectSettings", "localSettings", "flagSettings", "cliArg", atau "session"
• grant_scope: "once" atau "session" untuk permintaan izin yang disetujui tanpa menyimpan aturan ke file pengaturan
• circuit_breaker: Pemeriksaan safety bawaan, seperti "dangerousRemoval", "outsideReadsBlocked", atau "claudeSettingsFile"
• classifier_category: Dengan OTEL_LOG_TOOL_DETAILS=1, aturan bawaan di balik pemblokiran auto mode, seperti "data_exfiltration"
• hook_event: "pre_tool_use" untuk hook PreToolUse, atau "post_tool_use", "post_tool_use_failure", "stop", atau "subagent_stop" pada event "hook_review"
• tool_class: "bash" untuk Bash dan Monitor, "powershell", "file" untuk Read, Edit, Write, NotebookEdit, Glob, dan Grep, "web" untuk WebFetch dan WebSearch, "mcp", atau "other"
• tool_name: Nama tool, seperti "Bash" untuk tool bawaan, atau "mcp_tool", "skill_tool", "dynamic_tool", atau "other_tool"
• tool_source: "builtin", "mcp", atau "sdk_host_builtin_mcp", seperti pada tool_decision
• permission_mode: Mode izin panggilan saat diperiksa: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk", atau "auto"
• tool_use_id: ID panggilan, seperti pada tool_decision dan tool_result
• sandbox_violation_count: Jumlah koneksi atau permintaan berbeda dari perintah panggilan yang ditolak oleh proxy jaringan sandbox, "0" hingga "20" sebagai string. Penolakan dihitung untuk perintah dalam sandbox yang selesai di foreground
• sandbox_enabled: "true" jika sandboxing aktif untuk sesi, jika tidak "false"

Berikut adalah atribut milik event ini saat aturan deny dari pengaturan terkelola menolak perintah Bash:

{
  "event.name": "safety_event",
  "category": "managed_policy",
  "decision": "reject",
  "decision_source": "config",
  "reason_code": "rule:policySettings",
  "rule_source": "policySettings",
  "tool_class": "bash",
  "tool_name": "Bash",
  "tool_source": "builtin",
  "permission_mode": "default",
  "tool_use_id": "toolu_01ABC123...",
  "sandbox_violation_count": "0",
  "sandbox_enabled": "false"
}

Kategori event safety

Untuk menemukan penolakan proxy di bawah category apa pun, filter sandbox_violation_count yang ada dan bukan "0".

Panggilan tanpa event safety

Untuk menemukan panggilan yang ditolak karena tidak ada yang dapat menjawab permintaan izin tanpa kategori, cari event tool_decision yang melaporkan "reject" dengan source "config" dan tidak ada event safety yang memiliki tool_use_id yang sama. Penolakan seperti ini terjadi dalam eksekusi -p tanpa --permission-prompt-tool maupun --permission-prompts none.

Periksa panggilan seperti berikut untuk event tool_decision, karena panggilan tersebut tidak memiliki event safety kecuali event "sandbox_network", "sandbox_other", atau "hook_review" yang dikirim setelah panggilan tersebut berjalan:

• Panggilan yang disetujui pada permintaan izin tanpa kategori
• Panggilan yang disetujui oleh callback canUseTool atau tool --permission-prompt-tool pada permintaan izin yang hanya diharuskan oleh hook PreToolUse
• Panggilan AskUserQuestion atau ExitPlanMode, baik ditolak maupun tidak

Permintaan izin tanpa kategori

Permintaan izin tidak memiliki kategori saat tidak ada nilai category yang menyebutkan pemeriksaannya, seperti permintaan izin mode default untuk edit di dalam direktori kerja Anda.

Event perubahan mode izin

Dicatat ketika mode izin berubah, misalnya dari siklus Shift+Tab, keluar dari plan mode, atau pemeriksaan gerbang auto mode.

Untuk mengelompokkan panggilan tool berdasarkan mode izin saat masing-masing diperiksa, gunakan permission_mode pada Event keputusan tool.

Nama Event: claude_code.permission_mode_changed

Atribut:

• Semua atribut standar
• event.name: "permission_mode_changed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• from_mode: Mode izin sebelumnya, misalnya "default", "plan", "acceptEdits", "auto", atau "bypassPermissions"
• to_mode: Mode izin yang baru
• trigger: Penyebab perubahan, misalnya "shift_tab", "exit_plan_mode", atau "auto_gate_denied". Tidak ada untuk beberapa perubahan, seperti ketika SDK menetapkan mode izin melalui setPermissionMode()

Event autentikasi

Dicatat ketika /login atau /logout selesai.

Nama Event: claude_code.auth

Atribut:

• Semua atribut standar
• event.name: "auth"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• action: "login" atau "logout"
• success: "true" atau "false"
• auth_method: Metode autentikasi, seperti "oauth"
• error_category: Jenis error kategoris ketika aksi gagal. Pesan error mentah tidak pernah disertakan
• status_code: Kode status HTTP sebagai string ketika aksi gagal dengan error HTTP

Event koneksi server MCP

Dicatat ketika server MCP terhubung, terputus, atau gagal terhubung.

Nama Event: claude_code.mcp_server_connection

Atribut:

• Semua atribut standar
• event.name: "mcp_server_connection"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• status: "connected", "failed", atau "disconnected"
• transport_type: Transport server, seperti "stdio", "sse", atau "http"
• server_scope: Cakupan tempat server dikonfigurasi, seperti "user", "project", atau "local"
• duration_ms: Durasi percobaan koneksi dalam milidetik
• error_code: Kode error ketika koneksi gagal
• is_plugin: true ketika server disediakan oleh plugin, false jika tidak
• plugin_id_hash (ketika is_plugin adalah true): Hash stabil dari nama plugin dan marketplace, untuk mengelompokkan event berdasarkan plugin tanpa mengekspos namanya. Claude Code menghitungnya sebagaimana dijelaskan di bawah event plugin dimuat
• plugin.name (ketika is_plugin adalah true): Nama plugin yang menyediakan server. Untuk plugin pihak ketiga, ini adalah string literal "third-party" kecuali OTEL_LOG_TOOL_DETAILS=1; ini melindungi nama plugin pihak ketiga agar tidak muncul di log secara default. Plugin dari sumber resmi Anthropic selalu diidentifikasi berdasarkan nama. Atribut plugin_id_hash dan plugin.name mengalir ke backend pemantauan Anda sendiri dan tidak dikirim ke Anthropic
• server_name (ketika OTEL_LOG_TOOL_DETAILS=1): Nama server yang dikonfigurasi
• error (ketika OTEL_LOG_TOOL_DETAILS=1): Pesan error lengkap ketika koneksi gagal

Event error internal

Dicatat ketika Claude Code menangkap error internal yang tidak terduga. Hanya nama kelas error dan kode bergaya errno yang dicatat. Pesan error dan stack trace tidak pernah disertakan. Event ini tidak dipancarkan ketika berjalan terhadap Amazon Bedrock, Agent Platform milik Google Cloud, atau Microsoft Foundry, atau ketika DISABLE_ERROR_REPORTING ditetapkan.

Nama Event: claude_code.internal_error

Atribut:

• Semua atribut standar
• event.name: "internal_error"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• error_name: Nama kelas error, seperti "TypeError" atau "SyntaxError"
• error_code: Kode errno Node.js seperti "ENOENT" jika ada pada error

Event plugin diinstal

Dicatat ketika plugin selesai diinstal, baik dari perintah CLI claude plugin install maupun UI /plugin interaktif.

Nama Event: claude_code.plugin_installed

Atribut:

• Semua atribut standar
• event.name: "plugin_installed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• marketplace.is_official: "true" jika marketplace adalah marketplace resmi Anthropic, "false" jika tidak
• install.trigger: "cli" atau "ui"
• plugin.name: Nama plugin yang diinstal. Untuk marketplace pihak ketiga, ini hanya disertakan ketika OTEL_LOG_TOOL_DETAILS=1
• plugin.version: Versi plugin jika dideklarasikan dalam entri marketplace. Untuk marketplace pihak ketiga, ini hanya disertakan ketika OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace tempat plugin diinstal. Untuk marketplace pihak ketiga, ini hanya disertakan ketika OTEL_LOG_TOOL_DETAILS=1

Event plugin dimuat

Dicatat sekali per plugin yang diaktifkan pada awal sesi. Gunakan event ini untuk menginventarisasi plugin mana yang aktif di seluruh armada Anda, sebagai pelengkap plugin_installed yang mencatat aksi instalasi itu sendiri.

Nama Event: claude_code.plugin_loaded

Atribut:

• Semua atribut standar
• event.name: "plugin_loaded"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• plugin.name: nama plugin. Untuk plugin di luar marketplace resmi dan bundel bawaan, nilainya adalah "third-party" kecuali OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: marketplace tempat plugin diinstal, jika diketahui. Disamarkan menjadi "third-party" dengan kondisi yang sama seperti plugin.name
• plugin.version: versi dari manifes plugin. Hanya disertakan ketika nama tidak disamarkan dan manifes mendeklarasikan versi
• plugin.scope: kategori asal-usul plugin: "official", "community", "org", "user-local", atau "default-bundle"
• enabled_via: bagaimana plugin menjadi aktif: "default-enable", "org-policy", "admin-install", "seed-mount", atau "user-install". Nilai "admin-install" berarti plugin ditetapkan sebagai wajib atau instal otomatis untuk organisasi Anda di Organization settings > Plugins & skills. Sebelum v2.1.246, Claude Code melaporkan plugin ini sebagai "user-install" atau "seed-mount"
• plugin_id_hash: hash deterministik dari nama plugin dan marketplace, hanya dikirim ke exporter yang Anda konfigurasikan. Memungkinkan Anda menghitung plugin pihak ketiga yang berbeda yang dimuat di seluruh armada Anda tanpa mencatat namanya. Untuk plugin yang disinkronkan dari claude.ai, Claude Code melakukan hash pada nama plugin dengan nama marketplace yang dilaporkan claude.ai untuk plugin tersebut, atau dengan synced jika tidak ada. Sebelum v2.1.246, Claude Code tidak menggunakan nama marketplace yang dilaporkan claude.ai dalam hash
• has_hooks: apakah plugin menyumbangkan hook, melalui konfigurasi hook atau sebagai mod
• has_mcp: apakah plugin menyumbangkan server MCP
• host_owned_mcp: true ketika host SDK mengelola koneksi MCP plugin ini dan Claude Code melewatkan pembacaan konfigurasi server MCP plugin, false jika tidak
• skill_path_count: jumlah direktori skill yang dideklarasikan plugin
• command_path_count: jumlah direktori perintah yang dideklarasikan plugin
• agent_path_count: jumlah direktori agent yang dideklarasikan plugin
• safe_mode: "true" ketika sesi dimulai dengan --safe-mode, "false" jika tidak. Dalam safe mode, event ini hanya melaporkan inventaris yang dikonfigurasi; perintah, skill, hook, dan server MCP plugin tidak dimuat. Memerlukan Claude Code v2.1.169 atau lebih baru

Event skill diaktifkan

Dicatat ketika skill dipanggil, baik Claude memanggilnya melalui tool Skill maupun Anda menjalankannya sebagai perintah /.

Nama Event: claude_code.skill_activated

Atribut:

• Semua atribut standar
• event.name: "skill_activated"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• skill.name: Nama skill. Untuk skill yang ditentukan pengguna dan skill plugin pihak ketiga, nilainya adalah placeholder "custom_skill" kecuali OTEL_LOG_TOOL_DETAILS=1
• invocation_trigger: Cara skill dipicu ("user-slash", "claude-proactive", atau "nested-skill")
• skill.source: Asal skill dimuat (misalnya, "bundled", "userSettings", "projectSettings", "plugin")
• skill.kind: "workflow" ketika skill adalah skill workflow. Tidak ada jika sebaliknya
• plugin.name (ketika OTEL_LOG_TOOL_DETAILS=1 atau plugin berasal dari marketplace resmi): Nama plugin pemilik ketika skill disediakan oleh plugin
• marketplace.name (ketika OTEL_LOG_TOOL_DETAILS=1 atau plugin berasal dari marketplace resmi): Marketplace tempat plugin pemilik diinstal, ketika skill disediakan oleh plugin

Event at mention

Dicatat ketika Claude Code menyelesaikan @-mention dalam prompt. Tidak setiap mention memancarkan event: jalur keluar awal seperti penolakan izin, file yang terlalu besar, lampiran referensi PDF, dan kegagalan listing direktori kembali tanpa mencatat.

Setiap kali Claude Code membaca prompt, Claude Code mencatat paling banyak 100 event dengan mention_type berupa "agent" dan 100 dengan "mcp_resource". Mention yang melewati salah satu batas tersebut tetap diselesaikan tetapi tidak memancarkan event.

Nama Event: claude_code.at_mention

Atribut:

• Semua atribut standar
• event.name: "at_mention"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• mention_type: Jenis mention ("file", "directory", "agent", "mcp_resource", "peer"). Nilai "peer" berarti Anda menyebut salah satu sesi Claude Code Anda yang lain. Memerlukan Claude Code v2.1.232 atau lebih baru
• success: Apakah mention berhasil diselesaikan ("true" atau "false")

Event retry API habis

Dicatat sekali ketika permintaan API gagal setelah lebih dari satu percobaan. Dipancarkan bersama event api_error terakhir.

Nama Event: claude_code.api_retries_exhausted

Atribut:

• Semua atribut standar
• event.name: "api_retries_exhausted"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• model: Model yang digunakan
• error: Pesan error terakhir
• status_code: Kode status HTTP sebagai angka. Tidak ada untuk error non-HTTP.
• total_attempts: Jumlah total percobaan yang dilakukan
• total_retry_duration_ms: Total waktu wall-clock di seluruh percobaan
• speed: "fast" atau "normal"

Event hook terdaftar

Dicatat sekali per hook yang dikonfigurasi pada awal sesi. Gunakan event ini untuk menginventarisasi hook mana yang aktif di seluruh armada Anda, sebagai pelengkap event per eksekusi hook_execution_start dan hook_execution_complete.

Nama Event: claude_code.hook_registered

Atribut:

• Semua atribut standar
• event.name: "hook_registered"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• hook_event: jenis event hook, seperti "PreToolUse" atau "PostToolUse"
• hook_type: jenis implementasi hook: "command", "prompt", "mcp_tool", "http", atau "agent"
• hook_source: tempat hook didefinisikan: "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings", atau "pluginHook"
• safe_mode: "true" ketika sesi dimulai dengan --safe-mode, "false" jika tidak. Memerlukan Claude Code v2.1.169 atau lebih baru
• hook_matcher (ketika OTEL_LOG_TOOL_DETAILS=1): string matcher dari konfigurasi hook, jika ditetapkan
• plugin.name (ketika hook_source adalah "pluginHook"): nama plugin penyumbang. Untuk plugin di luar marketplace resmi dan bundel bawaan, nilainya adalah "third-party" kecuali OTEL_LOG_TOOL_DETAILS=1
• plugin_id_hash (ketika hook_source adalah "pluginHook"): hash deterministik dari nama plugin dan marketplace, hanya dikirim ke exporter yang Anda konfigurasikan. Memungkinkan Anda menghitung plugin penyumbang yang berbeda tanpa mencatat namanya. Claude Code menghitungnya sebagaimana dijelaskan di bawah event plugin dimuat

Event mulai eksekusi hook

Dicatat ketika satu atau lebih hook mulai dieksekusi untuk suatu event hook.

Nama Event: claude_code.hook_execution_start

Atribut:

• Semua atribut standar
• event.name: "hook_execution_start"
• event.timestamp: Timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bawah Atribut korelasi event
• hook_event: Jenis event hook, seperti "PreToolUse" atau "PostToolUse"
• hook_name: Nama hook lengkap termasuk matcher, seperti "PreToolUse:Write"
• num_hooks: Jumlah perintah hook yang cocok
• managed_only: "true" ketika hanya hook kebijakan terkelola yang diizinkan
• hook_source: "policySettings" atau "merged"
• safe_mode: "true" ketika sesi dimulai dengan --safe-mode, "false" jika tidak. Memerlukan Claude Code v2.1.169 atau lebih baru
• hook_definitions: Konfigurasi hook yang diserialisasi JSON. Hanya disertakan ketika tracing beta terperinci dan OTEL_LOG_TOOL_DETAILS=1 keduanya diaktifkan

Event penyelesaian eksekusi hook

Dicatat ketika semua hook untuk sebuah event hook telah selesai.

Nama Event: claude_code.hook_execution_complete

Atribut:

• Semua atribut standar
• event.name: "hook_execution_complete"
• event.timestamp: timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bagian Atribut korelasi event
• hook_event: Jenis event hook
• hook_name: Nama hook lengkap termasuk matcher
• num_hooks: Jumlah perintah hook yang cocok
• num_success: Jumlah yang selesai dengan sukses
• num_blocking: Jumlah yang mengembalikan keputusan pemblokiran
• num_non_blocking_error: Jumlah yang gagal tanpa memblokir
• num_cancelled: Jumlah yang dibatalkan sebelum selesai
• total_duration_ms: Durasi wall-clock dari semua hook yang cocok
• stdout_chars: Total karakter stdout di seluruh hook yang cocok yang berhasil. Memerlukan Claude Code v2.1.280 atau lebih baru
• additional_context_chars: Total karakter additionalContext yang dikembalikan oleh hook yang cocok. Memerlukan Claude Code v2.1.280 atau lebih baru
• system_message_chars: Total karakter systemMessage yang dikembalikan oleh hook yang cocok. Memerlukan Claude Code v2.1.280 atau lebih baru
• initial_user_message_chars: Total karakter initialUserMessage yang dikembalikan oleh hook yang cocok. Memerlukan Claude Code v2.1.280 atau lebih baru
• num_outputs_persisted: Jumlah output hook yang melebihi batas 10.000 karakter yang disimpan Claude Code ke sebuah file. Memerlukan Claude Code v2.1.280 atau lebih baru
• managed_only: "true" ketika hanya hook dari kebijakan terkelola yang diizinkan
• hook_source: "policySettings" atau "merged"
• safe_mode: "true" ketika sesi dimulai dengan --safe-mode, "false" jika tidak. Memerlukan Claude Code v2.1.169 atau lebih baru
• hook_definitions: Konfigurasi hook yang diserialisasi sebagai JSON. Hanya disertakan ketika detailed beta tracing dan OTEL_LOG_TOOL_DETAILS=1 keduanya diaktifkan

Event metrik plugin hook

Dicatat ketika hook plugin dari marketplace resmi memancarkan metrik per pemanggilan. Hanya plugin yang diinstal dari marketplace resmi Anthropic yang dapat memancarkan metrik ini. Plugin marketplace pihak ketiga dan hook yang dikonfigurasi pengguna tidak memancarkan ke event ini. Gunakan event ini untuk memantau perilaku plugin seperti tingkat temuan, biaya, dan durasi dari stack observabilitas Anda sendiri.

Nama Event: claude_code.hook_plugin_metrics

Atribut:

• Semua atribut standar
• event.name: "hook_plugin_metrics"
• event.timestamp: timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bagian Atribut korelasi event
• plugin_id: pengidentifikasi plugin dalam bentuk <name>@<marketplace>
• hook_event: jenis event hook yang memancarkan metrik
• Hingga 20 kunci metrik yang dipancarkan plugin. Nama cocok dengan ^[a-z][a-z0-9_]{0,39}$. Nilai berupa Boolean atau angka.

Event compaction

Dicatat ketika compaction percakapan selesai.

Nama Event: claude_code.compaction

Atribut:

• Semua atribut standar
• event.name: "compaction"
• event.timestamp: timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bagian Atribut korelasi event
• trigger: "auto" atau "manual"
• success: "true" atau "false"
• duration_ms: Durasi compaction
• pre_tokens: Perkiraan jumlah token sebelum compaction
• post_tokens: Perkiraan jumlah token setelah compaction
• error: Pesan kesalahan ketika compaction gagal
• precompute_reuse: Hanya ditetapkan jika trigger adalah "manual", atau jika trigger adalah "auto" untuk idle compaction dalam sesi terminal interaktif. Auto-compaction dapat menyiapkan ringkasan di latar belakang sebelum context window penuh, dan atribut ini mencatat apakah compaction menggunakan kembali ringkasan yang telah disiapkan tersebut. "hit" berarti ringkasan digunakan kembali; "miss_custom_instructions", "miss_hook", dan "miss_not_ready" memberikan alasan mengapa ringkasan baru dihitung sebagai gantinya

Event subagent selesai

Dicatat ketika sebuah subagent selesai dan mengembalikan hasilnya ke percakapan yang memulainya. Gunakan event ini untuk merangkum penggunaan tool dan waktu eksekusi berdasarkan jenis subagent; untuk rangkuman token atau biaya, gunakan penghitung token dan penghitung biaya yang difilter ke query_source "subagent", karena total_tokens pada event ini hanya mencakup permintaan terakhir. Kategori "subagent" juga menghitung permintaan dari hook berbasis agent, yang tidak memancarkan event subagent.

Nama Event: claude_code.subagent_completed

Atribut:

• Semua atribut standar
• event.name: "subagent_completed"
• event.timestamp: timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bagian Atribut korelasi event
• agent_type: Jenis subagent. Nama agent bawaan dan agent dari plugin marketplace resmi muncul apa adanya; nama agent lainnya diganti dengan "custom" kecuali OTEL_LOG_TOOL_DETAILS=1 diatur
• agent.source: Asal definisi agent: built-in, plugin, atau sumber pengaturan yang mendefinisikan agent kustom, seperti userSettings atau projectSettings
• is_built_in: Apakah subagent merupakan jenis agent bawaan
• is_async: Apakah subagent berjalan di latar belakang
• total_tokens: Jejak token dari permintaan API terakhir subagent: token input, pembuatan cache, pembacaan cache, dan output dari satu permintaan tersebut, kira-kira ukuran konteks subagent saat selesai. Bukan jumlah di seluruh eksekusi
• total_tool_uses: Jumlah panggilan tool yang dilakukan subagent di seluruh eksekusi
• duration_ms: Waktu eksekusi dalam milidetik
• model: Model yang ditetapkan untuk menjalankan subagent
• final_model: Model yang menghasilkan respons akhir subagent, yang berbeda dari model setelah peralihan di tengah eksekusi seperti fallback
• model_swapped: Apakah lebih dari satu model melayani permintaan subagent
• plugin_id_hash, plugin.name: Ada untuk agent yang disediakan plugin. Nama plugin marketplace resmi muncul apa adanya; nama plugin lainnya diganti dengan "third-party" kecuali OTEL_LOG_TOOL_DETAILS=1 diatur

Event survei umpan balik

Dicatat ketika survei kualitas sesi ditampilkan atau dijawab. Lihat Survei kualitas sesi untuk mengetahui apa yang dikumpulkan survei dan cara mengendalikannya.

Nama Event: claude_code.feedback_survey

Atribut:

• Semua atribut standar
• event.name: "feedback_survey"
• event.timestamp: timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bagian Atribut korelasi event
• event_type: Event siklus hidup survei, misalnya "appeared", "responded", atau "transcript_prompt_appeared"
• appearance_id: ID unik yang menghubungkan event yang dipancarkan untuk satu instans survei
• survey_type: Survei mana yang menghasilkan event. "session" adalah prompt penilaian "How is Claude doing?"
• response: Pilihan pengguna pada event responded
• enabled_via_override: true ketika CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL diatur. Dipancarkan sebagai Boolean, bukan string. Ada pada event survei session. Filter berdasarkan atribut ini untuk memastikan override diterapkan di seluruh armada

Event sapuan retensi

Dicatat sekali per eksekusi sapuan pembersihan retensi, yang menghapus transkrip sesi dan data aplikasi lainnya yang lebih lama dari pengaturan cleanupPeriodDays. Claude Code menjalankan sapuan di latar belakang paling banyak sekali per sesi, dan eksekusi yang tidak menghapus apa pun tetap memancarkan event. Jika Claude Code menjalankan sapuan di sesi mana pun pada mesin yang sama dalam 24 jam terakhir, Claude Code menunda sapuan sesi ini setidaknya 10 menit, sehingga sesi yang keluar lebih cepat tidak memancarkan apa pun. Ketika Anda menjalankan claude -p dengan --bare, Claude Code tidak menjalankan sapuan dan tidak memancarkan apa pun.

Seperti setiap event OTel di halaman ini, event ini hanya dikirim ke backend telemetri yang Anda konfigurasi. Memerlukan Claude Code v2.1.227 atau lebih baru.

Ketika Claude Code tidak dapat menentukan periode retensi dengan aman, Claude Code menjeda sapuan dan memancarkan event dengan result diatur ke "skipped" dan sebuah skip_reason. Ketika pengaturan terkelola mengatur cleanupPeriodDays, nilai terkelola mengunci periode retensi dan sapuan tetap berjalan meskipun file pengaturan di cakupan berprioritas lebih rendah rusak atau tidak valid. Ketika managed-settings.json itu sendiri tidak dapat dibaca, Claude Code tetap menjeda sapuan kecuali tingkat terkelola menyediakan cleanupPeriodDays dari tempat lain, seperti pengaturan terkelola server atau drop-in managed-settings.d/ di samping file yang rusak. Atribut penghitung penghapusan hanya ada ketika result bernilai "complete".

Nama Event: claude_code.retention_sweep

Atribut:

• Semua atribut standar
• event.name: "retention_sweep"
• event.timestamp: timestamp ISO 8601
• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bagian Atribut korelasi event
• result: "complete" ketika sapuan berjalan, "skipped" ketika Claude Code menjedanya
• period_days: Nilai cleanupPeriodDays dari pengaturan yang digabungkan, dalam hari, atau 30 ketika tidak ada sumber yang mengaturnya. Pada event yang dilewati, nilai yang akan digunakan sapuan, dihitung dari sumber pengaturan yang dapat dibaca Claude Code
• used_default: "true" ketika tidak ada sumber pengaturan yang dapat dibaca yang mengatur cleanupPeriodDays, "false" jika sebaliknya. Pada event complete, "true" berarti default 30 hari diterapkan
• skip_reason: Mengapa Claude Code menjeda sweep. Hanya ada ketika result adalah "skipped":
  • "user_source_disabled": Pengaturan pengguna dikecualikan, misalnya oleh flag --setting-sources atau opsi settingSources SDK, dan tidak ada sumber yang diaktifkan yang menyediakan cleanupPeriodDays
  • "settings_unknowable": File pengaturan tidak dapat dibaca atau diurai, sehingga cleanupPeriodDays atau desktopSessionCleanupPeriodDays mungkin diatur ke nilai yang tidak dapat dilihat Claude Code
  • "settings_invalid_key_set": Pengaturan memiliki error validasi dan cleanupPeriodDays atau desktopSessionCleanupPeriodDays diatur secara eksplisit, sehingga kembali ke default dapat menghapus atau menyimpan file yang bertentangan dengan pengaturan tersebut
  • "remote_settings_unknowable": Sesi di tab Code Claude Desktop pada deployment pihak ketiga meminta pengaturan terkelola server. Sesi tersebut tidak menerima respons yang dapat digunakan, sehingga cleanupPeriodDays mungkin diatur ke nilai yang tidak dapat dilihat Claude Code
• transcripts_deleted: Jumlah transkrip sesi, yaitu file tingkat atas ~/.claude/projects/*/*.jsonl, yang dihapus oleh sapuan
• transcripts_exempted_desktop: Jumlah transkrip yang melewati periode retensi yang dipertahankan oleh sapuan berdasarkan aturan Claude Desktop dan Cowork. Transkrip ini tidak dihitung dalam files_past_cutoff. Memerlukan Claude Code v2.1.248 atau lebih baru
• session_files_deleted: Jumlah artefak yang dihapus oleh sapuan file sesi: transkrip ditambah file pendamping per sesi seperti sidecar, rekaman, dan hasil tool
• artifacts_deleted: Total item yang dihapus sapuan di seluruh direktori data yang dicakupnya, termasuk file sesi. Beberapa sapuan menghitung seluruh pohon direktori yang dihapus sebagai satu item dan beberapa tahap pembersihan tidak berkontribusi pada penghitung, jadi perlakukan nilai ini sebagai batas bawah, bukan jumlah file yang tepat
• files_retained_fresh: File yang diperiksa dan dibiarkan di tempatnya karena masih berada dalam periode retensi. Hanya sapuan per file yang menghitungnya, sehingga nilainya merupakan batas bawah; nilai bukan nol adalah kondisi stabil yang normal
• files_past_cutoff: File yang lebih lama dari periode retensi yang gagal dihapus oleh sapuan, misalnya karena kesalahan permission atau file yang masih terbuka. Jumlah ini juga mencakup setiap folder usang yang ditemukan sapuan di bawah skills/synced/ atau plugins/synced/, terlepas dari apakah sapuan memindahkan folder tersebut ke tempat sampah. Selain folder tersebut, nilai di atas nol berarti ada file yang bertahan melewati periode retensi yang dikonfigurasi; nol bukan bukti bahwa tidak ada file yang bertahan, karena kegagalan penghapusan seluruh direktori dihitung dalam error_count
• error_count: Jumlah kesalahan yang ditemui sapuan saat mendaftar atau menghapus file

Event pengaturan terkelola terselesaikan

Dicatat bersama pengaturan terkelola yang diselesaikan oleh sebuah sesi: sekali saat sesi dimulai, lagi ketika pengaturan terkelola atau status policy helper berubah selama sesi, dan ketika Claude Code menolak untuk memulai atau mengakhiri sesi karena salah satu alasan yang tercantum dalam atribut error.type. Gunakan event ini untuk menemukan mesin yang berjalan pada sumber terkelola yang tidak terduga, mesin yang policy helper-nya gagal, dan alasan sebuah mesin menolak untuk memulai. Memerlukan Claude Code v2.1.274 atau lebih baru.

Secara default, event ini membawa sumber terkelola dan status policy helper, tetapi tidak membawa pengaturan itu sendiri. Untuk menambahkan atribut managed_settings.settings yang telah disamarkan dan digest managed_settings.resolved_sha256, atur OTEL_LOG_MANAGED_SETTINGS=1:

• Atur di blok env pada pengaturan terkelola, pengaturan pengguna, atau --settings, atau di lingkungan tempat Anda meluncurkan Claude Code. Nilai di pengaturan proyek atau lokal tidak mengaktifkannya, karena repositori yang di-clone dapat menulisnya.
• Pengaturan terkelola server dapat mengaturnya tanpa menampilkan dialog persetujuan keamanan, karena variabel ini hanya menambahkan kebijakan organisasi Anda sendiri yang telah disamarkan ke event yang sudah diterima organisasi Anda.

Dalam sesi interaktif di folder yang belum Anda percayai, Claude Code tidak mengekspor event penolakan.

Nama Event: claude_code.managed_settings_resolved

Atribut:

• Semua atribut standar

• event.name: "managed_settings_resolved"

• event.timestamp: timestamp ISO 8601

• event.sequence: penghitung per proses untuk mengurutkan event, dijelaskan di bagian Atribut korelasi event

• managed_settings.trigger: "startup" untuk event awal sesi, "change" ketika pengaturan terkelola atau status policy helper berubah kemudian dalam sesi, atau "refused" ketika kebijakan pengaturan terkelola menghentikan sesi. Claude Code mengirim event change hanya ketika sebuah atribut berbeda dari event terakhir yang dikirimnya, dan nilai pengaturan yang berubah tetap dihitung meskipun OTEL_LOG_MANAGED_SETTINGS dinonaktifkan

• error.type: alasan Claude Code menghentikan sesi. Hanya ada pada event refused:

  • "helper_failed": sebuah eksekusi policy helper gagal
  • "policy_invalid": pengaturan terkelola berisi kesalahan yang mencegah Claude Code memulai, atau sebuah sumber admin gagal dimuat karena alasan selain pembacaan yang ditolak, sehingga Claude Code tidak dapat memeriksa login organisasi atau penegakan penyedia
  • "provider_not_allowed": sesi akan menggunakan penyedia API, atau mengirim lalu lintas penyedia ke sebuah host, yang tidak diizinkan oleh daftar allowedProviders terkelola. Memerlukan Claude Code v2.1.285 atau lebih baru
  • "consent_rejected": pengguna menolak dialog persetujuan keamanan untuk pengaturan terkelola server
  • "force_refresh_failed": pengambilan pengaturan yang diwajibkan oleh forceRemoteSettingsRefresh gagal
  • "gateway_rejected": sebuah Claude apps gateway menjawab pemuatan pengaturan terkelola dengan HTTP 403
  • "version_below_minimum": versi Claude Code ini berada di bawah requiredMinimumVersion atau di atas requiredMaximumVersion
  • "_OTHER": pemuatan pengaturan terkelola Claude apps gateway gagal karena alasan lain

• managed_settings.sources: setiap sumber terkelola yang menyediakan setidaknya satu kunci kebijakan, prioritas tertinggi terlebih dahulu, termasuk sumber yang kuncinya tidak berlaku di bawah first-wins. Nilainya adalah "remote", "plist" atau "hklm" untuk kebijakan MDM atau tingkat OS, "file" untuk file pengaturan terkelola dan drop-in, "parent" ketika sebuah host penyemat menyediakan pengaturan, dan "hkcu" untuk nilai registri Windows HKCU ketika Claude Code membacanya. Sumber yang hanya membawa kunci kontrol, atau yang tidak dapat dibaca Claude Code, tidak dicantumkan. Dipancarkan sebagai array string, kosong ketika tidak ada sumber terkelola yang menyediakan kunci kebijakan

• managed_settings.source_behavior: nilai managedSourcesBehavior yang dibaca Claude Code, "first-wins" atau "merge". "first-wins" ketika tidak ada sumber yang mengatur kunci tersebut

• managed_settings.helper.state: status policy helper yang dikonfigurasi oleh sumber MDM atau file yang dipilih:

  • "ok": output helper berfungsi sebagai pengaturan terkelola
  • "bad_path", "not_a_file", "exit_nonzero", "timed_out", "oversize", "parse_failed", "envelope_invalid", atau "schema_rejected": eksekusi terakhir helper gagal. Kegagalan helper menjelaskan kasus-kasusnya
  • "none": tidak ada helper yang dikonfigurasi, atau sumber yang mengonfigurasinya bukan kebijakan MDM atau file pengaturan terkelola

• managed_settings.helper.applied: "output" selama output helper itu sendiri berfungsi sebagai pengaturan terkelola, "none" jika tidak

• managed_settings.helper.entry: "policyHelper" ketika Claude Code memilih sebuah policyHelper. Tidak ada ketika tidak ada helper yang dipilih

• managed_settings.helper.path: path helper yang dikonfigurasi. Ada setiap kali Claude Code memilih helper, terlepas dari apakah OTEL_LOG_MANAGED_SETTINGS diatur

• managed_settings.resolved_sha256 (ketika OTEL_LOG_MANAGED_SETTINGS=1): SHA-256 dari pengaturan terkelola yang diselesaikan sebelum penyamaran, diserialisasi sebagai JSON dengan kunci diurutkan secara rekursif dan tanpa spasi kosong. Mesin dengan digest yang sama menjalankan kebijakan yang sama. Claude Code mengirim digest hanya dengan opt-in karena kebijakan yang pendek dapat dipulihkan dengan melakukan hash terhadap tebakan. Tidak ada ketika tidak ada pengaturan terkelola yang diselesaikan, dan pada event refused

• managed_settings.settings (ketika OTEL_LOG_MANAGED_SETTINGS=1): nama dan bentuk pengaturan terkelola yang diselesaikan sebagai string JSON, dengan nilai-nilai disamarkan. Tidak ada pada event refused. Claude Code membangunnya dari skema pengaturannya:

  • Nama pengaturan yang dideklarasikan skema diekspor, dan kunci yang tidak dideklarasikan dihilangkan
  • Boolean, angka, dan nilai string yang dibatasi skema ke sekumpulan opsi tetap, seperti permissions.defaultMode, diekspor apa adanya. sandbox.network.httpProxyPort dan sandbox.network.socksProxyPort diekspor sebagai "[REDACTED]"
  • Setiap string lainnya, seperti model, apiKeyHelper, setiap nilai env, setiap URL, dan setiap perintah, diekspor sebagai "[REDACTED]"
  • Nama entri dari map, seperti nama variabel env dan ID plugin, diekspor apa adanya. Pengaturan yang entrinya tidak diberi tipe oleh skema, seperti vimInsertModeRemaps, diekspor sebagai satu "[REDACTED]", dan sandbox.ignoreViolations diekspor sebagai daftar dari daftar path-nya tanpa pola perintah
  • Sebuah daftar mempertahankan panjangnya, dengan setiap entri disamarkan menurut aturan yang sama
  • Aturan permissions.allow, permissions.deny, atau permissions.ask diekspor sebagai nama tool-nya dengan konten disamarkan, seperti Read([REDACTED]), ketika tool tersebut merupakan bawaan versi Claude Code ini atau merupakan referensi mcp__ seperti mcp__jira__create_issue. Aturan lainnya diekspor sebagai "[REDACTED]"
  • Hook mengikuti aturan yang sama, sehingga field opsi tetap dan numerik seperti type dan timeout ditampilkan, sementara setiap perintah, URL, matcher, dan kondisi if diekspor sebagai "[REDACTED]"

  Misalnya, pengaturan terkelola dengan apiKeyHelper, dua variabel env, dan sebuah aturan deny diekspor sebagai {"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}.

  Claude Code memotong nilai pada 8 KB UTF-8, dan nilai yang terpotong bukan JSON yang valid

• managed_settings.settings_truncated (ketika managed_settings.settings ada): true ketika Claude Code memotong managed_settings.settings pada 8 KB, false jika tidak. Dipancarkan sebagai Boolean, bukan string

Menafsirkan data metrik dan acara

Metrik dan acara yang diekspor mendukung berbagai analisis:

Pemantauan penggunaan

Pemantauan biaya

Metrik claude_code.cost.usage membantu dengan:

• Melacak tren penggunaan di seluruh tim atau individu
• Mengidentifikasi sesi penggunaan tinggi untuk optimasi
• Atribusi pengeluaran ke skill, plugin, atau jenis subagent tertentu melalui atribut skill.name, plugin.name, dan agent.name

[!NOTE]

Metrik biaya adalah perkiraan. Untuk data penagihan resmi, lihat penyedia API Anda (Claude Console, Amazon Bedrock, atau Google Cloud's Agent Platform).

Claude Code menghitung setiap respons streaming terhadap metrik biaya dan token tepat sekali, termasuk ketika gateway atau proxy di belakang ANTHROPIC_BASE_URL melakukan streaming penggunaan secara progresif di beberapa frame.

Peringatan dan segmentasi

Peringatan umum untuk dipertimbangkan:

• Lonjakan biaya
• Konsumsi token yang tidak biasa
• Volume sesi tinggi dari pengguna tertentu

Semua metrik dapat disegmentasikan berdasarkan atribut standar. Atribut model tersedia pada claude_code.token.usage, claude_code.cost.usage, dan claude_code.lines_of_code.count.

Rincian per-model dari commit hanya dapat didekati dengan menggabungkan terhadap metrik token atau biaya pada session.id, karena satu sesi dapat mencakup beberapa model. Filter sisi token atau biaya ke baris di mana query_source adalah "main" sehingga permintaan auxiliary dan subagent tidak mengatribusikan commit sesi ke model yang tidak membuatnya.

Deteksi kelelahan retry

Claude Code mencoba ulang permintaan API yang gagal secara internal dan hanya memancarkan acara claude_code.api_error tunggal setelah menyerah, jadi acara itu sendiri adalah sinyal terminal untuk permintaan tersebut. Upaya retry perantara tidak dicatat sebagai acara terpisah.

Atribut attempt pada acara mencatat jumlah upaya. CLAUDE_CODE_MAX_RETRIES default ke 10 dan dibatasi pada 15; jika CLAUDE_CODE_RETRY_WATCHDOG diatur, nilai default-nya lebih tinggi dan tidak ada batas.

Ketika permintaan menghabiskan semua retry pada kesalahan transien, attempt paling banyak satu lebih dari batas efektif tersebut: 11 secara default.

Nilai yang lebih rendah tetap dapat berarti retry telah habis: attempt dimulai lagi dari 1 setiap kali Claude Code mengirim ulang permintaan setelah kegagalan streaming.

Untuk membedakan sesi yang pulih dari sesi yang terhenti, kelompokkan acara berdasarkan session.id dan periksa apakah acara api_request yang lebih baru ada setelah kesalahan.

Analisis acara

Data acara memberikan wawasan terperinci tentang interaksi Claude Code:

Pola Penggunaan Alat: analisis acara hasil alat untuk mengidentifikasi:

• Alat yang paling sering digunakan
• Tingkat keberhasilan alat
• Waktu eksekusi alat rata-rata
• Pola kesalahan berdasarkan jenis alat

Pemantauan Kinerja: lacak durasi permintaan API dan waktu eksekusi alat untuk mengidentifikasi hambatan kinerja.

Memetakan token input ke konvensi semantik OpenTelemetry GenAI

Claude Code mengekspor jumlah token input sebagaimana muncul dalam blok usage pada respons API, sehingga nilai-nilai ini tidak menyertakan token yang dibaca dari atau ditulis ke prompt cache:

• input_tokens pada span claude_code.llm_request dan acara api_request
• Jenis "input" dari metrik claude_code.token.usage

Claude Code tidak mengatur atribut gen_ai.usage.*. Konvensi semantik OpenTelemetry GenAI menyatakan bahwa gen_ai.usage.input_tokens harus menyertakan token yang dibaca dari dan ditulis ke cache. Untuk menghitung total tersebut:

• Dari span atau acara: jumlahkan input_tokens, cache_read_tokens, dan cache_creation_tokens
• Dari metrik claude_code.token.usage: jumlahkan jenis "input", "cacheRead", dan "cacheCreation"

Konvensi tersebut juga mendefinisikan atribut terpisah untuk pembacaan cache dan penulisan cache:

• cache_read_tokens dipetakan ke gen_ai.usage.cache_read.input_tokens
• cache_creation_tokens dipetakan ke gen_ai.usage.cache_write.input_tokens. Versi konvensi yang lebih lama menamai atribut penulisan cache sebagai gen_ai.usage.cache_creation.input_tokens, jadi gunakan nama yang diharapkan oleh backend Anda.

Audit acara keamanan

Acara OpenTelemetry adalah sumber data audit untuk aktivitas Claude Code. Setiap acara membawa atribut identitas yang menghubungkan panggilan alat, aktivitas MCP, dan keputusan izin kembali ke pengguna yang memicunya. Pengekspor log OTLP dapat mengirimkan acara ini ke platform Security Information and Event Management (SIEM) apa pun dengan penerima OTLP, atau ke OpenTelemetry Collector yang meneruskan ke SIEM Anda.

Atribut tindakan untuk pengguna

Atribut standar pada setiap acara mencakup identitas pengguna yang diautentikasi: user.email, user.account_uuid, user.account_id, dan organization.id saat masuk dengan akun Claude atau, dalam sesi cloud, ketika kredensial sesi itu sendiri membawanya, ditambah user.id dan session.id per-sesi. user.id adalah pengidentifikasi berskop instalasi, kecuali pada sesi yang masuk ke Claude apps gateway melalui /login, di mana ini adalah subjek IdP dari token yang dikeluarkan gateway.

Dalam sesi yang dimulai pengembang, panggilan alat MCP, perintah Bash, dan pengeditan file oleh karena itu dikaitkan dengan pengembang tersebut. Claude Code tidak bertindak di bawah akun layanan terpisah di sana; identitas yang dicatat pada setiap acara adalah akun Claude pengembang itu sendiri, atau identitas IdP pengembang pada sesi Claude apps gateway. Dalam sesi saluran Claude Tag, Claude bekerja sebagai identitas bersama organisasi Anda.

Saat Claude Code diautentikasi dengan kunci API langsung, atau terhadap Amazon Bedrock, Google Cloud's Agent Platform, atau Microsoft Foundry, tidak ada akun Claude dalam sesi dan hanya user.id dan session.id yang diisi. Dalam penerapan ini, lampirkan identitas pengguna sendiri dengan OTEL_RESOURCE_ATTRIBUTES, atur per pengguna melalui file pengaturan terkelola atau pembungkus peluncuran. Sesi Claude apps gateway tidak memerlukan apa pun dari ini: lihat Atribut standar untuk identitas yang diekspor mereka.

export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

Audit aktivitas MCP

Untuk menangkap aktivitas server MCP dengan detail panggilan lengkap, aktifkan pengekspor log dan atur OTEL_LOG_TOOL_DETAILS=1. Setiap operasi MCP kemudian menghasilkan acara terstruktur yang membawa nama server, nama alat, dan argumen panggilan bersama atribut identitas standar:

Tanpa OTEL_LOG_TOOL_DETAILS, acara ini menghilangkan detail pengidentifikasi:

• tool_result: menyimpan mcp_server_scope dan tool_name diredaksi ke literal "mcp_tool" untuk server yang dikonfigurasi pengguna, menghilangkan konten argumen. Untuk server bawaan Claude Desktop, dalam sesi yang dimiliki Claude Desktop, ini juga menyimpan pasangan mcp_server_name/mcp_tool_name di dalam tool_parameters, pengecualian yang sama yang dipengaruhi host seperti tool_decision
• tool_decision: menyimpan tool_source dan tool_name diredaksi ke literal "mcp_tool" untuk server yang dikonfigurasi pengguna, menghilangkan konten argumen. Untuk server bawaan Claude Desktop, dalam sesi yang dimiliki Claude Desktop, ini juga menyimpan pasangan mcp_server_name/mcp_tool_name di dalam tool_parameters
• mcp_server_connection: menghilangkan server_name dan pesan kesalahan, tetapi menyimpan is_plugin, plugin_id_hash, dan plugin.name, dengan nama plugin non-Anthropic diredaksi ke literal "third-party", sehingga server yang disediakan plugin tetap dapat dibedakan tanpa pencatatan terperinci

Peta pertanyaan keamanan ke acara

Saat membangun aturan deteksi, cari sinyal yang ingin Anda pantau dan kueri backend Anda untuk acara dan atribut yang sesuai:

Claude Code memancarkan aliran acara mentah saja. Deteksi anomali, baselining, korelasi lintas sesi, dan peringatan adalah tanggung jawab backend SIEM atau observabilitas Anda.

Petakan jalur egress ke kontrol terkelola dan acara

Tabel ini memasangkan jalur yang dapat membawa konten sesi keluar dari mesin, ditambah retensi lokal, dengan kunci pengaturan terkelola yang membatasinya dan acara yang mencatatnya. Untuk apa yang dikirim Claude Code sendiri ke Anthropic, seperti laporan /feedback, lihat Penggunaan data. Nama-nama tersebut tertaut ke entri referensinya, yang memberikan nilai dan default.

Entri allowedHttpHookUrls, managed-mcp.json, dan acara hook memerlukan lebih dari yang ditunjukkan tabel:

• allowedHttpHookUrls: entri digabungkan di seluruh file pengaturan, sehingga pengembang dapat menambahkan ke daftar terkelola yang kosong. allowManagedHooksOnly menentukan hook mana yang dijalankan
• managed-mcp.json: untuk mematikan MCP, lihat Nonaktifkan MCP sepenuhnya. Untuk mengonfirmasi bahwa Claude Code membaca file tersebut, lihat Validasi konfigurasi
• Acara hook: Claude Code mencatat hook_execution_start dan hook_execution_complete satu kali per acara hook, mencakup setiap hook yang cocok. OTEL_LOG_TOOL_DETAILS=1 saja tidak mencatat URL hook HTTP. Konfigurasi hook hanya muncul di hook_definitions, yang juga memerlukan beta tracing terperinci

OTEL_LOG_TOOL_DETAILS=1 menambahkan string perintah, nama server dan tool, serta input tool ke acara ini. Detail tersebut dapat berisi konten sensitif yang sama dengan sesi itu sendiri, jadi aktifkan hanya jika collector Anda disetujui untuk menyimpan konten tersebut.

Periksa sapuan retensi

Untuk memberikan periode retensi yang sama ke setiap mesin, atur cleanupPeriodDays dalam pengaturan terkelola. Untuk memeriksa bahwa mesin menjalankan sapuan dengan nilai tersebut, kumpulkan acara retention_sweep. period_days dan penghitungnya berupa string, jadi konversikan ke angka sebelum Anda membandingkannya.

Mesin yang bekerja sebagaimana mestinya dapat tidak menghasilkan acara karena alasan seperti berikut:

• Tidak ada yang memulai Claude Code: tidak ada sapuan yang berjalan, dan mesin menyimpan datanya hingga peluncuran berikutnya
• Sesi tetap terbuka: Claude Code menjalankan sapuan paling banyak satu kali per sesi
• Sesi berakhir lebih awal: sapuan yang belum selesai saat sesi keluar tidak memancarkan apa pun, begitu pula sapuan yang berhenti karena kesalahan tak terduga

Sapuan tidak mencakup setiap jalur. Disimpan hingga Anda menghapusnya mencantumkan apa yang tetap ada, dan Hapus data lokal menunjukkan cara menghapusnya.

Kirim acara ke SIEM

Arahkan OTEL_EXPORTER_OTLP_LOGS_ENDPOINT ke penerima OTLP SIEM Anda, atau ke OpenTelemetry Collector yang meneruskan ke API ingest asli SIEM Anda. Contoh pengaturan terkelola berikut mengekspor acara saja, dengan detail alat lengkap diaktifkan untuk audit MCP dan Bash:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

Untuk mengonfirmasi acara tiba, kirimkan prompt dalam sesi yang berjalan di bawah konfigurasi ini dan periksa SIEM Anda untuk acara claude_code.user_prompt. Jika tidak ada yang tiba, jalankan Claude Code dengan claude --debug-file <path> dan periksa log itu untuk kesalahan ekspor [3P telemetry].

Pertimbangan backend

Pilihan backend metrik, log, dan traces Anda menentukan jenis analisis yang dapat Anda lakukan:

Backend untuk metrik

• Database deret waktu: Perhitungan laju, metrik agregat
• Toko kolumnar: Kueri kompleks, analisis pengguna unik
• Platform observabilitas lengkap: Kueri lanjutan, visualisasi, peringatan

Backend untuk acara dan log

• Sistem agregasi log: Pencarian teks lengkap, analisis log
• Toko kolumnar: Analisis acara terstruktur
• Platform observabilitas lengkap: Korelasi antara metrik dan acara

Backend untuk traces

Pilih backend yang mendukung penyimpanan distributed trace dan korelasi span:

• Sistem distributed tracing: Visualisasi span, request waterfalls, analisis latensi
• Platform observabilitas lengkap: Pencarian trace dan korelasi dengan metrik dan log

Untuk organisasi yang memerlukan metrik Pengguna Aktif Harian/Mingguan/Bulanan (DAU/WAU/MAU), pertimbangkan backend yang mendukung kueri nilai unik yang efisien.

Informasi layanan

Semua metrik dan acara diekspor dengan atribut sumber daya berikut:

• service.name: claude-code untuk sesi terminal, claude-code-desktop untuk sesi lokal yang dimulai dari tab Code di aplikasi Claude Desktop
• service.version: Versi Claude Code saat ini, atau versi aplikasi Desktop untuk sesi lokal tab Code
• os.type: Jenis sistem operasi (misalnya, linux, darwin, windows)
• os.version: String versi sistem operasi
• host.arch: Arsitektur host (misalnya, amd64, arm64)
• wsl.version: Nomor versi WSL (hanya ada saat berjalan di Windows Subsystem for Linux)
• Nama Meter: com.anthropic.claude_code

Jika pipeline pengumpul atau dasbor Anda memfilter pada service.name = claude-code, tambahkan claude-code-desktop ke filter untuk juga menangkap telemetri dari sesi lokal tab Code.

Sumber daya pengukuran ROI

Untuk panduan komprehensif tentang mengukur pengembalian investasi untuk Claude Code, termasuk pengaturan telemetri, analisis biaya, metrik produktivitas, dan pelaporan otomatis, lihat Panduan Pengukuran ROI Claude Code. Repositori ini menyediakan konfigurasi Docker Compose siap pakai, pengaturan Prometheus dan OpenTelemetry, dan template untuk menghasilkan laporan produktivitas yang terintegrasi dengan alat seperti Linear.

Keamanan dan privasi

• Ekspor OpenTelemetry ke backend Anda adalah opt-in dan memerlukan konfigurasi eksplisit. Untuk telemetri operasional terpisah Anthropic dan cara menonaktifkannya, lihat Penggunaan data
• Konten file mentah dan cuplikan kode tidak disertakan dalam metrik atau acara. Trace spans adalah jalur data terpisah: lihat poin OTEL_LOG_TOOL_CONTENT di bawah
• Saat diautentikasi melalui OAuth, user.email disertakan dalam atribut telemetri, dikirim hanya ke titik akhir OTel yang Anda konfigurasikan, tidak pernah ke Anthropic. Jika ini menjadi perhatian bagi organisasi Anda, bekerja dengan backend telemetri Anda untuk memfilter atau menyunting bidang ini
• Konten prompt pengguna tidak dikumpulkan secara default. Hanya panjang prompt yang dicatat. Untuk menyertakan konten prompt, atur OTEL_LOG_USER_PROMPTS=1. Saat diaktifkan:

  • Acara user_prompt membawa teks prompt dalam dua atribut, prompt dan prompt_text. Jika Anda membuang atau menyamarkan teks prompt acara berdasarkan nama atribut di collector Anda, sebutkan kedua atribut dalam aturan tersebut

    Processor attributes OpenTelemetry Collector ini menghapus kedua atribut dalam pipeline yang mencantumkannya:

    processors:
      attributes/drop-prompt-text:
        actions:
          - key: prompt
            action: delete
          - key: prompt_text
            action: delete
    

  • Dengan tracing aktif, span claude_code.interaction membawa teks prompt dalam atribut user_prompt-nya

  • Di bawah detailed beta tracing, spans juga membawa pesan pengguna baru, hasil tool, dan system reminder yang dikirim bersama setiap permintaan, teks system prompt, serta output model. Atribut konten di bawah detailed beta tracing mencantumkan setiap atribut. Acara claude_code.system_prompt membawa system prompt lengkap

• Teks respons asisten tidak dikumpulkan secara default. Hanya panjang respons yang dicatat. Untuk menyertakan teks respons, atur OTEL_LOG_ASSISTANT_RESPONSES=1. Seperti semua data OpenTelemetry dari Claude Code, teks respons dikirim hanya ke endpoint OTel yang Anda konfigurasikan, tidak pernah ke Anthropic. Ketika variabel ini tidak diatur, OTEL_LOG_USER_PROMPTS digunakan sebagai fallback, jadi atur OTEL_LOG_ASSISTANT_RESPONSES=0 jika Anda menginginkan konten prompt tanpa konten respons dalam acara. Di bawah detailed beta tracing, span claude_code.llm_request tetap membawa output model dalam response.model_output, yang mengikuti OTEL_LOG_USER_PROMPTS alih-alih variabel ini
• Argumen input tool dan parameter tidak dicatat secara default. Untuk menyertakannya, atur OTEL_LOG_TOOL_DETAILS=1. Untuk server bawaan Claude Desktop, dalam sesi yang dimiliki Claude Desktop, tool_decision dan tool_result membawa pasangan mcp_server_name/mcp_tool_name, nama yang ditulis host daripada konten argumen, bahkan dengan flag mati. Data ini dikirim hanya ke endpoint OTEL yang Anda konfigurasikan, tidak pernah ke Anthropic. Argumen mungkin masih berisi nilai sensitif, jadi konfigurasikan backend telemetri Anda untuk memfilter atau menyunting atribut ini sesuai kebutuhan. Saat diaktifkan:
  • Acara tool_result dan tool_decision menyertakan atribut tool_parameters dengan perintah Bash, nama server MCP dan tool, dan nama skill. Bidang seperti full_command dipancarkan tanpa pemotongan
  • Acara tool_result juga menyertakan atribut tool_input dengan jalur file, URL, pola pencarian, dan argumen lainnya. Nilai individual di atas 512 karakter dipotong dan total dibatasi hingga ~4 K karakter
  • Acara user_prompt menyertakan command_name verbatim untuk perintah custom, plugin, dan MCP
  • Penghitung biaya dan token dan acara api_request, api_error, dan api_refusal membawa nama agent, skill, plugin, dan server MCP dan tool yang sebenarnya dalam atribut atribusi mereka
  • Span claude_code.tool membawa atribut yang diturunkan dari input seperti file_path. Di bawah detailed beta tracing, span ini juga membawa atribut tool_input
• Konten alat tidak dicatat dalam trace spans secara default. Untuk menyertakannya, atur OTEL_LOG_TOOL_CONTENT=1. Span claude_code.tool kemudian membawa acara span tool.output dengan konten file mentah, output perintah Bash, dan apa yang dikembalikan alat MCP, WebFetch, dan WebSearch, dipotong pada batas konten (60 KB secara default) per atribut. Hasil dari alat MCP, WebFetch, dan WebSearch memerlukan Claude Code v2.1.283 atau lebih baru. Konten alat juga menjangkau spans melalui new_context, yang gatenya berbeda per span. Konfigurasikan backend telemetri Anda untuk memfilter atau menyunting atribut ini sesuai kebutuhan
• Badan permintaan dan respons API Anthropic Messages mentah tidak dicatat secara default. Untuk menyertakannya, atur OTEL_LOG_RAW_API_BODIES di shell, pengaturan pengguna, atau pengaturan terkelola Anda. Ini diabaikan dalam pengaturan proyek dan lokal. Badan berisi riwayat percakapan lengkap, termasuk system prompt, setiap giliran pengguna dan asisten sebelumnya, dan hasil alat, jadi mengaktifkan ini menyiratkan persetujuan untuk semua yang akan diungkapkan oleh flag konten OTEL_LOG_* lainnya. Claude Code selalu menyunting konten extended-thinking Claude dari badan ini, terlepas dari pengaturan lain. Nilai yang Anda atur menentukan bagaimana Claude Code mengirimkan badan:

  • Dengan =1, Claude Code memancarkan acara log api_request_body dan api_response_body untuk setiap panggilan API. Atribut body acara membawa muatan yang diserialisasi JSON, dipotong pada batas konten (60 KB secara default)

  • Dengan =file:<dir>, Claude Code menulis badan yang tidak dipotong ke file .request.json dan .response.json di bawah direktori tersebut, dan acara membawa jalur body_ref sebagai gantinya dari badan inline. Kirim direktori dengan pengumpul log atau sidecar daripada melalui aliran telemetri.

    Untuk setiap respons yang berhasil, Claude Code juga menambahkan satu baris ke index.jsonl di direktori tersebut, menghubungkan file respons ke file permintaan yang menghasilkannya dan ke pesan transkrip yang menjadi. Setiap baris tidak menyimpan konten pesan, dan bagian acara badan respons API mencantumkan bidangnya. File indeks memerlukan Claude Code v2.1.274 atau lebih baru

Memantau Claude Code di Amazon Bedrock

Untuk panduan pemantauan penggunaan Claude Code terperinci untuk Amazon Bedrock, lihat Claude Code Monitoring Implementation (Amazon Bedrock).