Dukungan OpenTelemetry saat ini dalam tahap beta dan detailnya dapat berubah.

​
OpenTelemetry di Claude Code

Claude Code mendukung metrik OpenTelemetry (OTel) untuk pemantauan dan observabilitas. Dokumen ini menjelaskan cara mengaktifkan dan mengonfigurasi OTel untuk Claude Code.

Semua metrik adalah data deret waktu yang diekspor melalui protokol metrik standar OpenTelemetry. Pengguna bertanggung jawab untuk memastikan backend metrik mereka dikonfigurasi dengan benar dan granularitas agregasi memenuhi persyaratan pemantauan mereka.

​
Mulai Cepat

Konfigurasikan OpenTelemetry menggunakan variabel lingkungan:

# 1. Aktifkan telemetri
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Pilih eksporter
export OTEL_METRICS_EXPORTER=otlp       # Pilihan: otlp, prometheus, 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 (default: 600000ms/10menit)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 detik

# 6. Jalankan Claude Code
claude

Interval ekspor default adalah 10 menit. Selama penyiapan, 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 atas pengaturan telemetri di seluruh organisasi. Lihat hierarki konfigurasi 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_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 diganti oleh pengguna.

​
Detail Konfigurasi

​
Variabel Konfigurasi Umum

Variabel LingkunganDeskripsiContoh Nilai
CLAUDE_CODE_ENABLE_TELEMETRYMengaktifkan pengumpulan telemetri (wajib)1
OTEL_METRICS_EXPORTERJenis eksporter yang digunakan (dipisahkan koma)console, otlp, prometheus
OTEL_EXPORTER_OTLP_PROTOCOLProtokol untuk eksporter OTLPgrpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint pengumpul OTLPhttp://localhost:4317
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: 10000)5000, 60000

​
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 memengaruhi persyaratan penyimpanan dan performa kueri di backend metrik Anda. Kardinalitas yang lebih rendah umumnya berarti performa yang lebih baik dan biaya penyimpanan yang lebih rendah tetapi data yang kurang terperinci untuk analisis.

​
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

​
Metrik yang Tersedia

Claude Code mengekspor metrik berikut:

Nama MetrikDeskripsiUnit
claude_code.session.countJumlah sesi CLI yang dimulaihitungan
claude_code.lines_of_code.countJumlah baris kode yang dimodifikasihitungan
claude_code.pull_request.countJumlah pull request yang dibuathitungan
claude_code.commit.countJumlah git commit yang dibuathitungan
claude_code.cost.usageBiaya sesi Claude CodeUSD
claude_code.token.usageJumlah token yang digunakantoken

​
Detail Metrik

Semua metrik berbagi atribut standar ini:

  • session.id: Pengidentifikasi sesi unik (dikontrol oleh OTEL_METRICS_INCLUDE_SESSION_ID)
  • app.version: Versi Claude Code saat ini (dikontrol oleh OTEL_METRICS_INCLUDE_VERSION)
  • organization.id: UUID organisasi (saat diautentikasi)
  • user.account_uuid: UUID akun (saat diautentikasi, dikontrol oleh OTEL_METRICS_INCLUDE_ACCOUNT_UUID)

​
1. Penghitung Sesi

Dipancarkan pada awal setiap sesi.

​
2. Penghitung Baris Kode

Dipancarkan ketika kode ditambahkan atau dihapus.

  • Atribut tambahan: type ("added" atau "removed")

​
3. Penghitung Pull Request

Dipancarkan saat membuat pull request melalui Claude Code.

​
4. Penghitung Commit

Dipancarkan saat membuat git commit melalui Claude Code.

​
5. Penghitung Biaya

Dipancarkan setelah setiap permintaan API.

  • Atribut tambahan: model

​
6. Penghitung Token

Dipancarkan setelah setiap permintaan API.

  • Atribut tambahan: type ("input", "output", "cacheRead", "cacheCreation") dan model

​
Menginterpretasikan Data Metrik

Metrik ini memberikan wawasan tentang pola penggunaan, produktivitas, dan biaya:

​
Pemantauan Penggunaan

MetrikPeluang Analisis
claude_code.token.usageUraikan 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 (Anthropic Console, 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.

​
Pertimbangan Backend

Jenis BackendTerbaik Untuk
Database deret waktu (Prometheus)Perhitungan tingkat, metrik agregat
Penyimpanan kolumnar (ClickHouse)Kueri kompleks, analisis pengguna unik
Platform observabilitas (Honeycomb, Datadog)Kueri lanjutan, visualisasi, peringatan

Untuk metrik DAU/WAU/MAU, pilih backend yang mendukung kueri 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

  • Telemetri bersifat opt-in dan memerlukan konfigurasi eksplisit
  • Informasi sensitif seperti kunci API atau konten file tidak pernah disertakan dalam metrik