Claude Code mendukung metrik dan acara OpenTelemetry (OTel) untuk pemantauan dan observabilitas. Semua metrik adalah data deret waktu yang diekspor melalui protokol metrik standar OpenTelemetry, dan acara diekspor melalui protokol log/acara OpenTelemetry. Adalah tanggung jawab pengguna untuk memastikan backend metrik dan log mereka dikonfigurasi dengan benar dan bahwa granularitas agregasi memenuhi persyaratan pemantauan mereka.
Dukungan OpenTelemetry saat ini dalam beta dan detail dapat berubah.

​
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
export OTEL_LOGS_EXPORTER=otlp          # Opsi: otlp, console

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

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

# 5. Untuk debugging: kurangi interval ekspor
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
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.
Untuk opsi konfigurasi lengkap, lihat spesifikasi OpenTelemetry.

​
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 berada 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
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.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}
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 LingkunganDeskripsiNilai Contoh
CLAUDE_CODE_ENABLE_TELEMETRYMengaktifkan pengumpulan telemetri (diperlukan)1
OTEL_METRICS_EXPORTERJenis pengekspor metrik (dipisahkan koma)console, otlp, prometheus
OTEL_LOGS_EXPORTERJenis pengekspor log/acara (dipisahkan koma)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLProtokol untuk pengekspor OTLP (semua sinyal)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTTitik akhir pengumpul OTLP (semua sinyal)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLProtokol untuk metrik (menimpa umum)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTTitik akhir metrik OTLP (menimpa umum)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLProtokol untuk log (menimpa umum)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTTitik akhir log OTLP (menimpa umum)http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSHeader autentikasi untuk OTLPAuthorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYKunci klien untuk autentikasi mTLSJalur ke file kunci klien
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATESertifikat klien untuk autentikasi mTLSJalur ke file sertifikat klien
OTEL_METRIC_EXPORT_INTERVALInterval ekspor dalam milidetik (default: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALInterval ekspor log dalam milidetik (default: 5000)1000, 10000
OTEL_LOG_USER_PROMPTSAktifkan pencatatan 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 LingkunganDeskripsiNilai DefaultContoh untuk Menonaktifkan
OTEL_METRICS_INCLUDE_SESSION_IDSertakan atribut session.id dalam metriktruefalse
OTEL_METRICS_INCLUDE_VERSIONSertakan atribut app.version dalam metrikfalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDSertakan atribut user.account_uuid dalam metriktruefalse
Variabel-variabel ini membantu mengontrol kardinalitas metrik, yang mempengaruhi persyaratan penyimpanan dan kinerja kueri di backend metrik Anda. Kardinalitas yang lebih rendah umumnya berarti kinerja yang lebih baik dan biaya penyimpanan yang lebih rendah tetapi data yang kurang granular untuk analisis.

​
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: 
{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​
Persyaratan Skrip

Skrip harus menampilkan JSON yang valid dengan pasangan kunci-nilai string yang mewakili header HTTP: 
#!/bin/bash
# Contoh: Beberapa header
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​
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 header-nya sendiri.

​
Dukungan Organisasi Multi-Tim

Organisasi dengan beberapa tim atau departemen dapat menambahkan atribut khusus untuk membedakan antara kelompok yang berbeda menggunakan variabel lingkungan OTEL_RESOURCE_ATTRIBUTES: 
# Tambahkan atribut khusus untuk identifikasi tim
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
Atribut khusus ini akan disertakan dalam semua metrik dan acara, memungkinkan Anda untuk:
  • 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 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 Company tidak 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
Contoh:
# ❌ Tidak valid - berisi spasi
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valid - gunakan garis bawah atau camelCase sebagai gantinya
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valid - kodekan persen karakter khusus jika diperlukan
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
Catatan: Mengutip seluruh pasangan kunci=nilai (misalnya, "key=value with spaces") tidak didukung oleh spesifikasi OpenTelemetry dan akan menghasilkan atribut yang diawali dengan tanda kutip.

​
Konfigurasi Contoh

# Debugging konsol (interval 1 detik)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/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

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

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

# Titik akhir/backend berbeda untuk metrik dan log
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.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317

# Hanya metrik (tanpa acara/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

# Hanya acara/log (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

​
Metrik dan Acara yang Tersedia

​
Atribut Standar

Semua metrik dan acara berbagi atribut standar ini:
AtributDeskripsiDikendalikan Oleh
session.idPengenal sesi unikOTEL_METRICS_INCLUDE_SESSION_ID (default: true)
app.versionVersi Claude Code saat iniOTEL_METRICS_INCLUDE_VERSION (default: false)
organization.idUUID Organisasi (saat diautentikasi)Selalu disertakan saat tersedia
user.account_uuidUUID Akun (saat diautentikasi)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (default: true)
terminal.typeJenis terminal (misalnya, iTerm.app, vscode, cursor, tmux)Selalu disertakan saat terdeteksi

​
Metrik

Claude Code mengekspor metrik berikut:
Nama MetrikDeskripsiUnit
claude_code.session.countJumlah sesi CLI yang dimulaicount
claude_code.lines_of_code.countJumlah baris kode yang dimodifikasicount
claude_code.pull_request.countJumlah permintaan tarik yang dibuatcount
claude_code.commit.countJumlah komit git yang dibuatcount
claude_code.cost.usageBiaya sesi Claude CodeUSD
claude_code.token.usageJumlah token yang digunakantokens
claude_code.code_edit_tool.decisionJumlah keputusan izin alat pengeditan kodecount
claude_code.active_time.totalTotal waktu aktif dalam detiks

​
Detail Metrik

​
Penghitung Sesi

Ditingkatkan pada awal setiap sesi. Atribut:

​
Penghitung Baris Kode

Ditingkatkan saat kode ditambahkan atau dihapus. Atribut:

​
Penghitung Permintaan Tarik

Ditingkatkan saat membuat permintaan tarik melalui Claude Code. Atribut:

​
Penghitung Komit

Ditingkatkan saat membuat komit git melalui Claude Code. Atribut:

​
Penghitung Biaya

Ditingkatkan setelah setiap permintaan API. Atribut:
  • Semua atribut standar
  • model: Pengenal model (misalnya, “claude-sonnet-4-5-20250929”)

​
Penghitung Token

Ditingkatkan setelah setiap permintaan API. Atribut:
  • Semua atribut standar
  • type: ("input", "output", "cacheRead", "cacheCreation")
  • model: Pengenal model (misalnya, “claude-sonnet-4-5-20250929”)

​
Penghitung Keputusan Alat Pengeditan 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:

​
Acara

Claude Code mengekspor acara berikut melalui log/acara OpenTelemetry (saat OTEL_LOGS_EXPORTER dikonfigurasi):

​
Acara Prompt Pengguna

Dicatat saat pengguna mengirimkan prompt. Nama Acara: claude_code.user_prompt Atribut:
  • Semua atribut standar
  • event.name: "user_prompt"
  • event.timestamp: Stempel waktu ISO 8601
  • prompt_length: Panjang prompt
  • prompt: Konten prompt (diredaksi secara default, aktifkan dengan OTEL_LOG_USER_PROMPTS=1)

​
Acara Hasil Alat

Dicatat saat alat menyelesaikan eksekusi. Nama Acara: claude_code.tool_result Atribut:
  • Semua atribut standar
  • event.name: "tool_result"
  • event.timestamp: Stempel waktu ISO 8601
  • tool_name: Nama alat
  • success: "true" atau "false"
  • duration_ms: Waktu eksekusi dalam milidetik
  • error: 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

​
Acara Permintaan API

Dicatat untuk setiap permintaan API ke Claude. Nama Acara: claude_code.api_request Atribut:
  • Semua atribut standar
  • event.name: "api_request"
  • event.timestamp: Stempel waktu ISO 8601
  • model: Model yang digunakan (misalnya, “claude-sonnet-4-5-20250929”)
  • cost_usd: Biaya perkiraan dalam USD
  • duration_ms: Durasi permintaan dalam milidetik
  • input_tokens: Jumlah token input
  • output_tokens: Jumlah token output
  • cache_read_tokens: Jumlah token yang dibaca dari cache
  • cache_creation_tokens: Jumlah token yang digunakan untuk pembuatan cache

​
Acara Kesalahan API

Dicatat saat permintaan API ke Claude gagal. Nama Acara: claude_code.api_error Atribut:
  • Semua atribut standar
  • event.name: "api_error"
  • event.timestamp: Stempel waktu ISO 8601
  • model: Model yang digunakan (misalnya, “claude-sonnet-4-5-20250929”)
  • error: Pesan kesalahan
  • status_code: Kode status HTTP (jika berlaku)
  • duration_ms: Durasi permintaan dalam milidetik
  • attempt: Nomor percobaan (untuk permintaan yang dicoba ulang)

​
Acara Keputusan Alat

Dicatat saat keputusan izin alat dibuat (terima/tolak). Nama Acara: claude_code.tool_decision Atribut:
  • Semua atribut standar
  • event.name: "tool_decision"
  • event.timestamp: Stempel waktu ISO 8601
  • tool_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 Acara

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

MetrikPeluang Analisis
claude_code.token.usagePecahkan berdasarkan type (input/output), pengguna, tim, atau model
claude_code.session.countLacak adopsi dan keterlibatan dari waktu ke waktu
claude_code.lines_of_code.countUkur produktivitas dengan melacak penambahan/penghapusan kode
claude_code.commit.count & claude_code.pull_request.countPahami dampak pada alur kerja pengembangan

​
Pemantauan Biaya

Metrik claude_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 (Konsol Claude, AWS Bedrock, atau Google Cloud Vertex).

​
Peringatan dan Segmentasi

Peringatan umum yang perlu dipertimbangkan:
  • Lonjakan biaya
  • Konsumsi token yang tidak biasa
  • Volume sesi tinggi dari pengguna tertentu
Semua metrik dapat disegmentasikan berdasarkan user.account_uuid, organization.id, session.id, model, dan app.version.

​
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.

​
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
  • Toko kolumnar (misalnya, ClickHouse): Kueri kompleks, analisis pengguna unik
  • Platform observabilitas lengkap (misalnya, Honeycomb, Datadog): Kueri lanjutan, visualisasi, peringatan

​
Untuk Acara/Log:

  • Sistem agregasi log (misalnya, Elasticsearch, Loki): Pencarian teks lengkap, analisis log
  • Toko kolumnar (misalnya, ClickHouse): Analisis acara terstruktur
  • Platform observabilitas lengkap (misalnya, Honeycomb, Datadog): Korelasi antara metrik dan acara
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
  • service.version: Versi Claude Code saat ini
  • 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

​
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 bersifat opt-in dan memerlukan konfigurasi eksplisit
  • Informasi sensitif seperti kunci API atau konten file tidak pernah disertakan dalam metrik atau acara
  • Konten prompt pengguna diredaksi secara default - hanya panjang prompt yang dicatat. Untuk mengaktifkan pencatatan prompt pengguna, atur OTEL_LOG_USER_PROMPTS=1

​
Memantau Claude Code di Amazon Bedrock

Untuk panduan pemantauan penggunaan Claude Code terperinci untuk Amazon Bedrock, lihat Implementasi Pemantauan Claude Code (Bedrock).