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. Tanggung jawab pengguna untuk memastikan backend metrik dan logs mereka dikonfigurasi dengan benar dan granularitas agregasi memenuhi kebutuhan pemantauan mereka.

Dukungan OpenTelemetry saat ini dalam versi beta dan detail dapat berubah.

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

Interval ekspor default adalah 60 detik untuk metrik dan 5 detik untuk logs. Selama setup, Anda mungkin ingin menggunakan interval yang lebih pendek untuk tujuan debugging. Ingat untuk mereset 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 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

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 didefinisikan dalam file pengaturan terkelola memiliki prioritas tinggi dan tidak dapat ditimpa oleh pengguna.

Detail Konfigurasi

Variabel Konfigurasi Umum

Variabel LingkunganDeskripsiContoh Nilai
CLAUDE_CODE_ENABLE_TELEMETRYMengaktifkan pengumpulan telemetri (diperlukan)1
OTEL_METRICS_EXPORTERJenis eksporter metrik (dipisahkan koma)console, otlp, prometheus
OTEL_LOGS_EXPORTERJenis eksporter logs/events (dipisahkan koma)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLProtokol untuk eksporter OTLP (semua sinyal)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint kolektor OTLP (semua sinyal)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLProtokol untuk metrik (menimpa umum)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTEndpoint metrik OTLP (menimpa umum)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLProtokol untuk logs (menimpa umum)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTEndpoint logs 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 mTLSPath ke file kunci klien
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATESertifikat klien untuk autentikasi mTLSPath ke file sertifikat klien
OTEL_METRIC_EXPORT_INTERVALInterval ekspor dalam milidetik (default: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALInterval ekspor logs dalam milidetik (default: 5000)1000, 10000
OTEL_LOG_USER_PROMPTSAktifkan 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 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 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.

Header Dinamis

Untuk lingkungan enterprise 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 mengeluarkan JSON yang valid dengan pasangan kunci-nilai string yang mewakili header HTTP:

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

Keterbatasan Penting

Header diambil hanya saat startup, bukan selama runtime. Ini karena keterbatasan arsitektur eksporter OpenTelemetry.

Untuk skenario yang memerlukan refresh token yang sering, gunakan OpenTelemetry Collector sebagai proxy yang dapat merefresh header-nya sendiri.

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 alert untuk tim tertentu

Persyaratan format penting untuk OTEL_RESOURCE_ATTRIBUTES:

Variabel lingkungan OTEL_RESOURCE_ATTRIBUTES mengikuti spesifikasi W3C Baggage, yang memiliki persyaratan format yang ketat:

  • Tidak boleh ada spasi: Nilai tidak boleh mengandung spasi. Misalnya, user.organizationName=My Company tidak valid
  • Format: Harus berupa pasangan key=value yang dipisahkan koma: key1=value1,key2=value2
  • Karakter yang diizinkan: Hanya karakter US-ASCII kecuali karakter kontrol, whitespace, tanda kutip ganda, koma, titik koma, dan backslash
  • Karakter khusus: Karakter di luar rentang yang diizinkan harus dikodekan dengan persen

Contoh:

# ❌ Tidak valid - mengandung spasi
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

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

# ✅ Valid - encode karakter khusus dengan persen jika diperlukan
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Catatan: Mengutip seluruh pasangan key=value (misalnya, "key=value with spaces") tidak didukung oleh spesifikasi OpenTelemetry dan akan menghasilkan atribut yang diawali dengan tanda kutip.

Contoh Konfigurasi

# Debugging console (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

# Multiple 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:

AtributDeskripsiDikontrol Oleh
session.idIdentifier sesi unikOTEL_METRICS_INCLUDE_SESSION_ID (default: true)
app.versionVersi Claude Code saat iniOTEL_METRICS_INCLUDE_VERSION (default: false)
organization.idUUID organisasi (saat terautentikasi)Selalu disertakan saat tersedia
user.account_uuidUUID akun (saat terautentikasi)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 pull request yang dibuatcount
claude_code.commit.countJumlah commit 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 tool pengeditan kodecount
claude_code.active_time.totalTotal waktu aktif dalam detiks

Detail Metrik

Penghitung Sesi

Ditambah pada awal setiap sesi.

Atribut:

Penghitung Baris Kode

Ditambah saat kode ditambahkan atau dihapus.

Atribut:

Penghitung Pull Request

Ditambah saat membuat pull request melalui Claude Code.

Atribut:

Penghitung Commit

Ditambah saat membuat commit git melalui Claude Code.

Atribut:

Penghitung Biaya

Ditambah setelah setiap permintaan API.

Atribut:

  • Semua atribut standar
  • model: Identifier model (misalnya, “claude-3-5-sonnet-20241022”)

Penghitung Token

Ditambah setelah setiap permintaan API.

Atribut:

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

Penghitung Keputusan Tool Edit Kode

Ditambah saat pengguna menerima atau menolak penggunaan tool Edit, MultiEdit, Write, atau NotebookEdit.

Atribut:

  • Semua atribut standar
  • tool: Nama tool ("Edit", "MultiEdit", "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 secara aktif menggunakan Claude Code (bukan waktu idle). Metrik ini ditambah selama interaksi pengguna seperti mengetik prompt atau menerima respons.

Atribut:

Event

Claude Code mengekspor event berikut melalui 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 Tool

Dicatat saat tool menyelesaikan eksekusi.

Nama Event: claude_code.tool_result

Atribut:

  • Semua atribut standar
  • event.name: "tool_result"
  • event.timestamp: Timestamp ISO 8601
  • tool_name: Nama tool
  • success: "true" atau "false"
  • duration_ms: Waktu eksekusi dalam milidetik
  • error: Pesan error (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 tool (saat tersedia)
    • Untuk tool Bash: termasuk bash_command, full_command, timeout, description, sandbox

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 (misalnya, “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 (misalnya, “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 Tool

Dicatat saat 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
  • tool_name: Nama tool (misalnya, “Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit”, dll.)
  • decision: Baik "accept" atau "reject"
  • source: Sumber keputusan - "config", "user_permanent", "user_temporary", "user_abort", atau "user_reject"

Menginterpretasikan 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

MetrikPeluang Analisis
claude_code.token.usageBreakdown 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 optimisasi

Metrik biaya adalah perkiraan. Untuk data penagihan resmi, rujuk ke penyedia API Anda (Anthropic Console, AWS Bedrock, atau Google Cloud Vertex).

Alerting dan Segmentasi

Alert 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 Tool: Analisis event hasil tool untuk mengidentifikasi:

  • Tool yang paling sering digunakan
  • Tingkat keberhasilan tool
  • Waktu eksekusi tool rata-rata
  • Pola error berdasarkan jenis tool

Pemantauan Performa: Lacak durasi permintaan API dan waktu eksekusi tool 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 (misalnya, Prometheus): Kalkulasi rate, metrik teragregasi
  • Columnar stores (misalnya, ClickHouse): Query kompleks, analisis pengguna unik
  • Platform observabilitas lengkap (misalnya, Honeycomb, Datadog): Query lanjutan, visualisasi, alerting

Untuk Events/Logs:

  • Sistem agregasi log (misalnya, Elasticsearch, Loki): Pencarian full-text, analisis log
  • Columnar stores (misalnya, ClickHouse): Analisis event terstruktur
  • Platform observabilitas lengkap (misalnya, 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 dan event diekspor dengan atribut resource 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 return on investment untuk Claude Code, termasuk setup telemetri, analisis biaya, metrik produktivitas, dan pelaporan otomatis, lihat Panduan Pengukuran ROI Claude Code. Repository ini menyediakan konfigurasi Docker Compose yang siap pakai, setup Prometheus dan OpenTelemetry, dan template untuk menghasilkan laporan produktivitas yang terintegrasi dengan tool 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 event
  • Konten prompt pengguna disensor secara default - hanya panjang prompt yang dicatat. Untuk mengaktifkan logging prompt pengguna, atur OTEL_LOG_USER_PROMPTS=1