Pemantauan

Claude Code mendukung metrik dan event OpenTelemetry (OTel) untuk pemantauan dan observabilitas.

Semua metrik adalah data time series yang diekspor melalui protokol metrik standar OpenTelemetry, dan event diekspor melalui protokol logs/events OpenTelemetry. Merupakan tanggung jawab pengguna untuk memastikan backend metrik dan logs mereka dikonfigurasi dengan benar dan granularitas agregasi memenuhi kebutuhan pemantauan mereka.

​

Mulai Cepat

Konfigurasikan OpenTelemetry menggunakan variabel lingkungan:

# 1. Aktifkan telemetri
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Pilih eksporter (keduanya 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 endpoint OTLP (untuk eksporter 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
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 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 terletak di:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux: /etc/claude-code/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"
  }
}

​

Detail Konfigurasi

​

Variabel Konfigurasi Umum

​

Kontrol Kardinalitas Metrik

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

Variabel ini membantu mengontrol kardinalitas metrik, yang mempengaruhi kebutuhan penyimpanan dan performa query di backend metrik Anda. Kardinalitas yang lebih rendah umumnya berarti performa yang lebih baik dan biaya penyimpanan yang lebih rendah tetapi data yang kurang granular untuk analisis.

​

Dukungan Organisasi Multi-Tim

Organisasi dengan beberapa tim atau departemen dapat menambahkan atribut kustom untuk membedakan antara grup 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 akan disertakan dalam semua metrik dan event, memungkinkan Anda untuk:

• Memfilter metrik berdasarkan tim atau departemen
• Melacak biaya per pusat biaya
• Membuat dashboard khusus tim
• Mengatur peringatan untuk tim tertentu

​

Contoh Konfigurasi

# 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 eksporter
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Endpoint/backend berbeda untuk metrik dan logs
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 events/logs)
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 events/logs (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 Event yang Tersedia

​

Atribut Standar

Semua metrik dan event berbagi atribut standar ini:

​

Metrik

Claude Code mengekspor metrik berikut:

​

Detail Metrik

​

Penghitung Sesi

Bertambah di awal setiap sesi.

Atribut:

• Semua atribut standar

​

Penghitung Baris Kode

Bertambah saat kode ditambahkan atau dihapus.

Atribut:

• Semua atribut standar
• type: ("added", "removed")

​

Penghitung Pull Request

Bertambah saat membuat pull request melalui Claude Code.

Atribut:

• Semua atribut standar

​

Penghitung Commit

Bertambah saat membuat commit git melalui Claude Code.

Atribut:

• Semua atribut standar

​

Penghitung Biaya

Bertambah setelah setiap permintaan API.

Atribut:

• Semua atribut standar
• model: Pengenal model (mis., “claude-3-5-sonnet-20241022”)

​

Penghitung Token

Bertambah setelah setiap permintaan API.

Atribut:

• Semua atribut standar
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Pengenal model (mis., “claude-3-5-sonnet-20241022”)

​

Penghitung Keputusan Alat Pengeditan Kode

Bertambah saat pengguna menerima atau menolak penggunaan alat Edit, MultiEdit, Write, atau NotebookEdit.

Atribut:

• Semua atribut standar
• tool: Nama alat ("Edit", "MultiEdit", "Write", "NotebookEdit")
• decision: Keputusan pengguna ("accept", "reject")
• language: Bahasa pemrograman file yang diedit (mis., "TypeScript", "Python", "JavaScript", "Markdown"). Mengembalikan "unknown" untuk ekstensi file yang tidak dikenali.

​

Event

Claude Code mengekspor event berikut melalui protokol logs/events OpenTelemetry (saat OTEL_LOGS_EXPORTER dikonfigurasi):

​

Event Prompt Pengguna

Dicatat saat pengguna mengirimkan prompt.

Nama Event: claude_code.user_prompt

Atribut:

• Semua atribut standar
• event.name: "user_prompt"
• event.timestamp: Timestamp ISO 8601
• prompt_length: Panjang prompt
• prompt: Konten prompt (disensor secara default, aktifkan dengan OTEL_LOG_USER_PROMPTS=1)

​

Event Hasil Alat

Dicatat saat alat menyelesaikan eksekusi.

Nama Event: claude_code.tool_result

Atribut:

• Semua atribut standar
• event.name: "tool_result"
• event.timestamp: Timestamp ISO 8601
• name: Nama alat
• success: "true" atau "false"
• duration_ms: Waktu eksekusi dalam milidetik
• error: Pesan error (jika gagal)

​

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
• model: Model yang digunakan (mis., “claude-3-5-sonnet-20241022”)
• cost_usd: Perkiraan biaya 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

​

Event Error API

Dicatat saat permintaan API ke Claude gagal.

Nama Event: claude_code.api_error

Atribut:

• Semua atribut standar
• event.name: "api_error"
• event.timestamp: Timestamp ISO 8601
• model: Model yang digunakan (mis., “claude-3-5-sonnet-20241022”)
• error: Pesan error
• status_code: Kode status HTTP (jika berlaku)
• duration_ms: Durasi permintaan dalam milidetik
• attempt: Nomor percobaan (untuk permintaan yang dicoba ulang)

​

Event Keputusan Alat

Dicatat saat keputusan izin alat dibuat (terima/tolak).

Nama Event: claude_code.tool_decision

Atribut:

• Semua atribut standar
• event.name: "tool_decision"
• event.timestamp: Timestamp ISO 8601
• tool_name: Nama alat (mis., “Read”, “Edit”, “MultiEdit”, “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 Event

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

​

Pemantauan Biaya

Metrik claude_code.cost.usage membantu dengan:

• Melacak tren penggunaan di seluruh tim atau individu
• Mengidentifikasi sesi penggunaan tinggi untuk optimisasi

​

Peringatan dan Segmentasi

Peringatan umum yang perlu dipertimbangkan:

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

Semua metrik dapat disegmentasi berdasarkan user.account_uuid, organization.id, session.id, model, dan app.version.

​

Analisis Event

Data event memberikan wawasan detail tentang interaksi Claude Code:

Pola Penggunaan Alat: Analisis event hasil alat untuk mengidentifikasi:

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

Pemantauan Performa: Lacak durasi permintaan API dan waktu eksekusi alat untuk mengidentifikasi bottleneck performa.

​

Pertimbangan Backend

Pilihan backend metrik dan logs Anda akan menentukan jenis analisis yang dapat Anda lakukan:

​

Untuk Metrik:

• Database time series (mis., Prometheus): Perhitungan rate, metrik teragregasi
• Columnar stores (mis., ClickHouse): Query kompleks, analisis pengguna unik
• Platform observabilitas lengkap (mis., Honeycomb, Datadog): Query lanjutan, visualisasi, peringatan

​

Untuk Events/Logs:

• Sistem agregasi log (mis., Elasticsearch, Loki): Pencarian teks lengkap, analisis log
• Columnar stores (mis., ClickHouse): Analisis event terstruktur
• Platform observabilitas lengkap (mis., Honeycomb, Datadog): Korelasi antara metrik dan event

Untuk organisasi yang memerlukan metrik Daily/Weekly/Monthly Active User (DAU/WAU/MAU), pertimbangkan backend yang mendukung query nilai unik yang efisien.

​

Informasi Layanan

Semua metrik diekspor dengan:

• Nama Layanan: claude-code
• Versi Layanan: Versi Claude Code saat ini
• Nama Meter: com.anthropic.claude_code

​

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 event
• Konten prompt pengguna disensor secara default - hanya panjang prompt yang dicatat. Untuk mengaktifkan logging prompt pengguna, atur OTEL_LOG_USER_PROMPTS=1