Dukungan OpenTelemetry saat ini dalam versi beta dan detail dapat berubah.
Mulai Cepat
Konfigurasikan OpenTelemetry menggunakan variabel lingkungan:Interval ekspor default adalah 60 detik untuk metrik dan 5 detik untuk log. Selama pengaturan, Anda mungkin ingin menggunakan interval yang lebih pendek untuk tujuan debugging. Ingat untuk mengatur ulang ini untuk penggunaan produksi.
Konfigurasi Administrator
Administrator dapat mengonfigurasi pengaturan OpenTelemetry untuk semua pengguna melalui file pengaturan terkelola. Ini memungkinkan kontrol terpusat pengaturan telemetri di seluruh organisasi. Lihat prioritas pengaturan untuk informasi lebih lanjut tentang bagaimana pengaturan diterapkan. File pengaturan terkelola terletak di:- macOS:
/Library/Application Support/ClaudeCode/managed-settings.json - Linux dan WSL:
/etc/claude-code/managed-settings.json - Windows:
C:\ProgramData\ClaudeCode\managed-settings.json
Pengaturan terkelola dapat didistribusikan melalui MDM (Mobile Device Management) atau solusi manajemen perangkat lainnya. Variabel lingkungan yang ditentukan dalam file pengaturan terkelola memiliki prioritas tinggi dan tidak dapat ditimpa oleh pengguna.
Detail Konfigurasi
Variabel Konfigurasi Umum
| Variabel Lingkungan | Deskripsi | Nilai Contoh |
|---|---|---|
CLAUDE_CODE_ENABLE_TELEMETRY | Mengaktifkan pengumpulan telemetri (diperlukan) | 1 |
OTEL_METRICS_EXPORTER | Jenis pengekspor metrik (dipisahkan koma) | console, otlp, prometheus |
OTEL_LOGS_EXPORTER | Jenis pengekspor log/peristiwa (dipisahkan koma) | console, otlp |
OTEL_EXPORTER_OTLP_PROTOCOL | Protokol untuk pengekspor OTLP (semua sinyal) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_ENDPOINT | Titik akhir pengumpul OTLP (semua sinyal) | http://localhost:4317 |
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | Protokol untuk metrik (menimpa umum) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Titik akhir metrik OTLP (menimpa umum) | http://localhost:4318/v1/metrics |
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Protokol untuk log (menimpa umum) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Titik akhir log OTLP (menimpa umum) | http://localhost:4318/v1/logs |
OTEL_EXPORTER_OTLP_HEADERS | Header autentikasi untuk OTLP | Authorization=Bearer token |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY | Kunci klien untuk autentikasi mTLS | Jalur ke file kunci klien |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE | Sertifikat klien untuk autentikasi mTLS | Jalur ke file sertifikat klien |
OTEL_METRIC_EXPORT_INTERVAL | Interval ekspor dalam milidetik (default: 60000) | 5000, 60000 |
OTEL_LOGS_EXPORT_INTERVAL | Interval ekspor log dalam milidetik (default: 5000) | 1000, 10000 |
OTEL_LOG_USER_PROMPTS | Aktifkan logging konten prompt pengguna (default: dinonaktifkan) | 1 untuk mengaktifkan |
Kontrol Kardinalitas Metrik
Variabel lingkungan berikut mengontrol atribut mana yang disertakan dalam metrik untuk mengelola kardinalitas:| Variabel Lingkungan | Deskripsi | Nilai Default | Contoh untuk Menonaktifkan |
|---|---|---|---|
OTEL_METRICS_INCLUDE_SESSION_ID | Sertakan atribut session.id dalam metrik | true | false |
OTEL_METRICS_INCLUDE_VERSION | Sertakan atribut app.version dalam metrik | false | true |
OTEL_METRICS_INCLUDE_ACCOUNT_UUID | Sertakan atribut user.account_uuid dalam metrik | true | false |
Header Dinamis
Untuk lingkungan perusahaan yang memerlukan autentikasi dinamis, Anda dapat mengonfigurasi skrip untuk menghasilkan header secara dinamis:Konfigurasi Pengaturan
Tambahkan ke.claude/settings.json Anda:
Persyaratan Skrip
Skrip harus menampilkan JSON yang valid dengan pasangan kunci-nilai string yang mewakili header HTTP:Batasan Penting
Header diambil hanya saat startup, bukan selama runtime. Ini karena keterbatasan arsitektur pengekspor OpenTelemetry. Untuk skenario yang memerlukan penyegaran token yang sering, gunakan OpenTelemetry Collector sebagai proxy yang dapat menyegarkan headernya sendiri.Dukungan Organisasi Multi-Tim
Organisasi dengan beberapa tim atau departemen dapat menambahkan atribut khusus untuk membedakan antara kelompok yang berbeda menggunakan variabel lingkunganOTEL_RESOURCE_ATTRIBUTES:
- Filter metrik berdasarkan tim atau departemen
- Lacak biaya per pusat biaya
- Buat dasbor khusus tim
- Atur peringatan untuk tim tertentu
Persyaratan pemformatan penting untuk OTEL_RESOURCE_ATTRIBUTES:Variabel lingkungan Catatan: Mengutip seluruh pasangan kunci=nilai (misalnya,
OTEL_RESOURCE_ATTRIBUTES mengikuti spesifikasi W3C Baggage, yang memiliki persyaratan pemformatan yang ketat:- Tidak ada spasi yang diizinkan: Nilai tidak dapat berisi spasi. Misalnya,
user.organizationName=My Companytidak valid - Format: Harus berupa pasangan kunci=nilai yang dipisahkan koma:
key1=value1,key2=value2 - Karakter yang diizinkan: Hanya karakter US-ASCII yang tidak termasuk karakter kontrol, spasi, tanda kutip ganda, koma, titik koma, dan garis miring terbalik
- Karakter khusus: Karakter di luar rentang yang diizinkan harus dikodekan persen
"key=value with spaces") tidak didukung oleh spesifikasi OpenTelemetry dan akan menghasilkan atribut yang diawali dengan tanda kutip.Konfigurasi Contoh
Metrik dan Peristiwa yang Tersedia
Atribut Standar
Semua metrik dan peristiwa berbagi atribut standar ini:| Atribut | Deskripsi | Dikendalikan Oleh |
|---|---|---|
session.id | Pengidentifikasi sesi unik | OTEL_METRICS_INCLUDE_SESSION_ID (default: true) |
app.version | Versi Claude Code saat ini | OTEL_METRICS_INCLUDE_VERSION (default: false) |
organization.id | UUID Organisasi (saat diautentikasi) | Selalu disertakan saat tersedia |
user.account_uuid | UUID Akun (saat diautentikasi) | OTEL_METRICS_INCLUDE_ACCOUNT_UUID (default: true) |
terminal.type | Jenis terminal (misalnya, iTerm.app, vscode, cursor, tmux) | Selalu disertakan saat terdeteksi |
Metrik
Claude Code mengekspor metrik berikut:| Nama Metrik | Deskripsi | Unit |
|---|---|---|
claude_code.session.count | Jumlah sesi CLI yang dimulai | count |
claude_code.lines_of_code.count | Jumlah baris kode yang dimodifikasi | count |
claude_code.pull_request.count | Jumlah permintaan tarik yang dibuat | count |
claude_code.commit.count | Jumlah komit git yang dibuat | count |
claude_code.cost.usage | Biaya sesi Claude Code | USD |
claude_code.token.usage | Jumlah token yang digunakan | tokens |
claude_code.code_edit_tool.decision | Jumlah keputusan izin alat pengedit kode | count |
claude_code.active_time.total | Total waktu aktif dalam detik | s |
Detail Metrik
Penghitung Sesi
Ditingkatkan pada awal setiap sesi. Atribut:- Semua atribut standar
Penghitung Baris Kode
Ditingkatkan saat kode ditambahkan atau dihapus. Atribut:- Semua atribut standar
type: ("added","removed")
Penghitung Permintaan Tarik
Ditingkatkan saat membuat permintaan tarik melalui Claude Code. Atribut:- Semua atribut standar
Penghitung Komit
Ditingkatkan saat membuat komit git melalui Claude Code. Atribut:- Semua atribut standar
Penghitung Biaya
Ditingkatkan setelah setiap permintaan API. Atribut:- Semua atribut standar
model: Pengidentifikasi model (misalnya, “claude-sonnet-4-5-20250929”)
Penghitung Token
Ditingkatkan setelah setiap permintaan API. Atribut:- Semua atribut standar
type: ("input","output","cacheRead","cacheCreation")model: Pengidentifikasi model (misalnya, “claude-sonnet-4-5-20250929”)
Penghitung Keputusan Alat Pengedit Kode
Ditingkatkan saat pengguna menerima atau menolak penggunaan alat Edit, Write, atau NotebookEdit. Atribut:- Semua atribut standar
tool: Nama alat ("Edit","Write","NotebookEdit")decision: Keputusan pengguna ("accept","reject")language: Bahasa pemrograman file yang diedit (misalnya,"TypeScript","Python","JavaScript","Markdown"). Mengembalikan"unknown"untuk ekstensi file yang tidak dikenali.
Penghitung Waktu Aktif
Melacak waktu aktual yang dihabiskan untuk menggunakan Claude Code secara aktif (bukan waktu idle). Metrik ini ditingkatkan selama interaksi pengguna seperti mengetik prompt atau menerima respons. Atribut:- Semua atribut standar
Peristiwa
Claude Code mengekspor peristiwa berikut melalui log/peristiwa OpenTelemetry (saatOTEL_LOGS_EXPORTER dikonfigurasi):
Peristiwa Prompt Pengguna
Dicatat saat pengguna mengirimkan prompt. Nama Peristiwa:claude_code.user_prompt
Atribut:
- Semua atribut standar
event.name:"user_prompt"event.timestamp: Stempel waktu ISO 8601prompt_length: Panjang promptprompt: Konten prompt (disensor secara default, aktifkan denganOTEL_LOG_USER_PROMPTS=1)
Peristiwa Hasil Alat
Dicatat saat alat menyelesaikan eksekusi. Nama Peristiwa:claude_code.tool_result
Atribut:
- Semua atribut standar
event.name:"tool_result"event.timestamp: Stempel waktu ISO 8601tool_name: Nama alatsuccess:"true"atau"false"duration_ms: Waktu eksekusi dalam milidetikerror: Pesan kesalahan (jika gagal)decision: Baik"accept"atau"reject"source: Sumber keputusan -"config","user_permanent","user_temporary","user_abort", atau"user_reject"tool_parameters: String JSON yang berisi parameter khusus alat (saat tersedia)- Untuk alat Bash: mencakup
bash_command,full_command,timeout,description,sandbox
- Untuk alat Bash: mencakup
Peristiwa Permintaan API
Dicatat untuk setiap permintaan API ke Claude. Nama Peristiwa:claude_code.api_request
Atribut:
- Semua atribut standar
event.name:"api_request"event.timestamp: Stempel waktu ISO 8601model: Model yang digunakan (misalnya, “claude-sonnet-4-5-20250929”)cost_usd: Biaya perkiraan dalam USDduration_ms: Durasi permintaan dalam milidetikinput_tokens: Jumlah token inputoutput_tokens: Jumlah token outputcache_read_tokens: Jumlah token yang dibaca dari cachecache_creation_tokens: Jumlah token yang digunakan untuk pembuatan cache
Peristiwa Kesalahan API
Dicatat saat permintaan API ke Claude gagal. Nama Peristiwa:claude_code.api_error
Atribut:
- Semua atribut standar
event.name:"api_error"event.timestamp: Stempel waktu ISO 8601model: Model yang digunakan (misalnya, “claude-sonnet-4-5-20250929”)error: Pesan kesalahanstatus_code: Kode status HTTP (jika berlaku)duration_ms: Durasi permintaan dalam milidetikattempt: Nomor percobaan (untuk permintaan yang dicoba ulang)
Peristiwa Keputusan Alat
Dicatat saat keputusan izin alat dibuat (terima/tolak). Nama Peristiwa:claude_code.tool_decision
Atribut:
- Semua atribut standar
event.name:"tool_decision"event.timestamp: Stempel waktu ISO 8601tool_name: Nama alat (misalnya, “Read”, “Edit”, “Write”, “NotebookEdit”, dll.)decision: Baik"accept"atau"reject"source: Sumber keputusan -"config","user_permanent","user_temporary","user_abort", atau"user_reject"
Menafsirkan Data Metrik dan Peristiwa
Metrik yang diekspor oleh Claude Code memberikan wawasan berharga tentang pola penggunaan dan produktivitas. Berikut adalah beberapa visualisasi dan analisis umum yang dapat Anda buat:Pemantauan Penggunaan
| Metrik | Peluang Analisis |
|---|---|
claude_code.token.usage | Pecah berdasarkan type (input/output), pengguna, tim, atau model |
claude_code.session.count | Lacak adopsi dan keterlibatan seiring waktu |
claude_code.lines_of_code.count | Ukur produktivitas dengan melacak penambahan/penghapusan kode |
claude_code.commit.count & claude_code.pull_request.count | Pahami dampak pada alur kerja pengembangan |
Pemantauan Biaya
Metrikclaude_code.cost.usage membantu dengan:
- Melacak tren penggunaan di seluruh tim atau individu
- Mengidentifikasi sesi penggunaan tinggi untuk optimasi
Metrik biaya adalah perkiraan. Untuk data penagihan resmi, lihat penyedia API Anda (Claude Console, AWS Bedrock, atau Google Cloud Vertex).
Peringatan dan Segmentasi
Peringatan umum untuk dipertimbangkan:- Lonjakan biaya
- Konsumsi token yang tidak biasa
- Volume sesi tinggi dari pengguna tertentu
user.account_uuid, organization.id, session.id, model, dan app.version.
Analisis Peristiwa
Data peristiwa memberikan wawasan terperinci tentang interaksi Claude Code: Pola Penggunaan Alat: Analisis peristiwa hasil alat untuk mengidentifikasi:- Alat yang paling sering digunakan
- Tingkat keberhasilan alat
- Waktu eksekusi alat rata-rata
- Pola kesalahan berdasarkan jenis alat
Pertimbangan Backend
Pilihan backend metrik dan log Anda akan menentukan jenis analisis yang dapat Anda lakukan:Untuk Metrik:
- Database deret waktu (misalnya, Prometheus): Perhitungan laju, metrik agregat
- Penyimpanan kolumnar (misalnya, ClickHouse): Kueri kompleks, analisis pengguna unik
- Platform observabilitas lengkap (misalnya, Honeycomb, Datadog): Kueri lanjutan, visualisasi, peringatan
Untuk Peristiwa/Log:
- Sistem agregasi log (misalnya, Elasticsearch, Loki): Pencarian teks lengkap, analisis log
- Penyimpanan kolumnar (misalnya, ClickHouse): Analisis peristiwa terstruktur
- Platform observabilitas lengkap (misalnya, Honeycomb, Datadog): Korelasi antara metrik dan peristiwa
Informasi Layanan
Semua metrik dan peristiwa diekspor dengan atribut sumber daya berikut:service.name:claude-codeservice.version: Versi Claude Code saat inios.type: Jenis sistem operasi (misalnya,linux,darwin,windows)os.version: String versi sistem operasihost.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
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.Pertimbangan Keamanan/Privasi
- Telemetri adalah opt-in dan memerlukan konfigurasi eksplisit
- Informasi sensitif seperti kunci API atau konten file tidak pernah disertakan dalam metrik atau peristiwa
- Konten prompt pengguna disensor secara default - hanya panjang prompt yang dicatat. Untuk mengaktifkan logging prompt pengguna, atur
OTEL_LOG_USER_PROMPTS=1