OpenTelemetry Claude Code: Metrik, Event, dan Biaya

Pertanyaan yang membuat saya menyiapkan ini bukan berapa yang kami belanjakan. Melainkan hal mana di antara semua ini yang membelanjakannya. Angka bulanan memberi tahu Anda bahwa sebuah tim memakai Claude Code; ia tidak memberi tahu bahwa satu MCP server menyumbang sepertiga tokennya, dan jelas tidak memberi tahu skill mana yang sedang berjalan ketika itu terjadi.

Telemetrinya menjawab itu, dan daftar atribut pada metrik biayalah sebabnya. Tulisan ini membahas setup minimalnya, delapan metrik dan dua yang benar-benar penting, aliran event beserta pengenal korelasinya, opsi content logging yang merupakan keputusan kebijakan alih-alih konfigurasi, dan kendali kardinalitas yang menentukan apakah collector Anda selamat menghadapi tim besar.

Enam variabel dan Anda sudah mengekspor

Tidak ada agent yang perlu dipasang dan tidak ada yang perlu dijalankan berdampingan dengan Claude Code. Ia berbicara OTLP langsung, jadi seluruh konfigurasinya berupa environment variable yang diarahkan ke collector yang sudah Anda punya. Administrator meletakkan blok yang sama di bagian environment pada managed settings, yang menimpa setting developer dan menghapus variabel per-signal yang bertentangan sehingga tujuannya terkunci.

# The whole setup. Put it in the env block of managed settings
# to lock the destination for a fleet, or export it locally.

CLAUDE_CODE_ENABLE_TELEMETRY=1        # required, nothing exports without it
OTEL_METRICS_EXPORTER=otlp            # otlp | prometheus | console | none
OTEL_LOGS_EXPORTER=otlp               # otlp | console | none
OTEL_EXPORTER_OTLP_PROTOCOL=grpc      # grpc | http/json | http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4317
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# Export intervals, if the defaults do not suit your collector:
OTEL_METRIC_EXPORT_INTERVAL=60000     # ms, default 60s
OTEL_LOGS_EXPORT_INTERVAL=5000        # ms, default 5s

# Verify: look for claude_code.session.count in your backend.
# Logs only? Submit a prompt and look for the user_prompt event.
# Nothing arriving? claude --debug shows OTel export errors.

Delapan metrik, dan dua yang benar-benar berguna

Set lengkapnya memetakan aktivitas dengan baik, tetapi sebagian besarnya konteks, bukan sinyal. Jumlah sesi dan total baris kode menjadi perabot dashboard yang bagus dan alert yang buruk. Dua yang layak dibangun di atasnya adalah biaya dan pemakaian token, karena atribusinya.

# Eight metrics. The two most people actually need are the
# last two on this list, not the first.

claude_code.session.count            start_type
claude_code.lines_of_code.count      type, model
claude_code.pull_request.count
claude_code.commit.count
claude_code.code_edit_tool.decision  tool_name, decision, source, language
claude_code.active_time.total        seconds, by type

claude_code.cost.usage               USD. Attributes go far beyond model:
                                     query_source, speed, effort,
                                     agent.name, skill.name, plugin.name,
                                     marketplace.name, mcp_server.name,
                                     mcp_tool.name

claude_code.token.usage              tokens. type, model, query_source,
                                     speed, effort

Daftar atribut itulah seluruh alasan mengerjakan ini dengan benar. Biaya yang dipecah per MCP server dan tool MCP memberi tahu apakah sebuah connector sepadan dengan ongkosnya. Dipecah per skill dan plugin, ia memberi tahu kustomisasi tim mana yang mahal. Dipecah per speed dan effort, ia memberi tahu apakah seseorang meninggalkan sesinya di effort level tinggi selama sepekan. Tidak satu pun terlihat dari total tagihan.

Aliran event, dan cara menyambungkannya

Event membawa apa yang tidak bisa dibawa metrik: request satuan, hasil tool, error, dan penolakan. Tiga atribut korelasi membuat alirannya bisa disambungkan, dan mengetahuinya mengubah setumpuk event menjadi jejak yang benar-benar bisa diikuti:

• Pengenal prompt yang menautkan setiap event yang dihasilkan satu prompt pengguna — kunci penyambung untuk pertanyaan berapa biaya satu request itu.
• Pengenal pesan yang cocok dengan transkrip sesi, sehingga sebuah event bisa dikaitkan kembali ke apa yang benar-benar dilihat pengguna.
• Pengenal client request, yang juga dikirim sebagai header request, dan itulah yang Anda sebutkan saat menanyakan sebuah request tertentu ke Anthropic.
• Event API request membawa token input, output, cache-read, dan cache-creation secara terpisah, dan itu cara terbersih memantau kesehatan cache satu tim ketimbang satu statusline pada satu waktu.

Content logging adalah keputusan kebijakan

Lima variabel terpisah menentukan apakah isi sesungguhnya sebuah sesi meninggalkan mesin, dan mereka sengaja dipisahkan karena membawa risiko berbeda. Mencatat detail tool adalah kendali audit yang wajar. Mencatat prompt pengguna dan respons asisten berarti collector Anda kini menyimpan percakapannya, dan kebijakan retensi collector Anda kini menjadi kebijakan retensi data AI Anda.

# Content logging is opt-in, per kind, and each of these is a
# policy decision rather than a configuration one.

OTEL_LOG_USER_PROMPTS=1          # the actual prompt text
OTEL_LOG_ASSISTANT_RESPONSES=1   # the actual model responses
OTEL_LOG_TOOL_DETAILS=1          # tool parameters, commands, skill names
OTEL_LOG_TOOL_CONTENT=1          # tool input/output — requires tracing
OTEL_LOG_RAW_API_BODIES=1        # or file:<dir> to write bodies to disk

CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH=61440   # default, UTF-16 code units

# Cardinality controls, with their DEFAULTS shown. Session id
# is on by default, which is the one to think about at scale.
OTEL_METRICS_INCLUDE_SESSION_ID=true
OTEL_METRICS_INCLUDE_ACCOUNT_UUID=true
OTEL_METRICS_INCLUDE_VERSION=false
OTEL_METRICS_INCLUDE_ENTRYPOINT=false

Apa yang sebenarnya layak dijadikan alert

Dashboard itu mudah dan alert adalah bagian sulitnya, karena sebagian besar metrik ini adalah aktivitas, bukan kesehatan. Empat ini punya ambang yang bisa dipertahankan alasannya.

Empat alert yang layak dimiliki:

Kardinalitas, sebelum collector Anda menyadarinya

Session id dan pengenal akun disertakan pada metrik secara default; versi dan entrypoint tidak. Default itu tepat untuk tim kecil dan keliru untuk tim besar — session id tidak terbatas, jadi setiap sesi menciptakan time series baru, dan beberapa ratus developer yang menjalankan beberapa sesi sehari akan membuatnya terasa.

Empat sakelar mengendalikannya, dan pendekatan jujurnya adalah memutuskan pertanyaan apa yang sedang Anda jawab. Kalau Anda butuh atribusi per sesi, pertahankan dan sesuaikan ukuran collector-nya. Kalau Anda hanya butuh total per pengguna, matikan session id dan pertahankan pengenal akun; Anda kehilangan kemampuan bertanya tentang satu sesi dan Anda berhenti membayar satu series per sesi selamanya.

Memverifikasinya, dengan urutan yang menghemat waktu

Tiga pemeriksaan, dengan urutan ini, karena masing-masing menyingkirkan lapisan berbeda:

1. Cari metrik session count di backend Anda. Kalau ia sampai, berarti exporter, endpoint, dan kredensialnya semua benar.
2. Kalau Anda hanya mengonfigurasi logs, kirim sebuah prompt dan cari event user prompt — metrik dan log punya variabel exporter terpisah dan salah satunya bisa salah konfigurasi sendirian.
3. Kalau tidak ada yang sampai, jalankan dengan flag debug, yang memunculkan error ekspor OTel yang jika tidak akan senyap.

Siapkan ini sebelum Anda membutuhkannya, karena pertanyaan yang dijawabnya semuanya bersifat retrospektif. Konfigurasinya enam variabel dan satu sore; nilainya muncul pertama kali ketika seseorang bertanya kenapa bulan lalu berbiaya sebesar itu, dan jawabannya berupa rincian per tool MCP alih-alih angkat bahu. Hanya saja, buat keputusan content logging-nya dengan sengaja, dan tuliskan apa arti kebijakan retensi collector Anda sekarang — karena begitu prompt mengalir ke sana, kebijakan itu menjadi bagian dari penanganan data AI Anda entah ada yang menuliskannya atau tidak.