Claude Platform Docs
AdminOpenTelemetry

OpenTelemetry untuk Claude API

Lacak permintaan Messages API, penggunaan alat, dan sesi Managed Agents Anda dengan span OpenTelemetry dari Claude SDK dan Claude API.

Claude API dan SDK dapat melakukan "tracing" (penelusuran) terhadap permintaan Messages API, penggunaan alat, dan sesi Managed Agents Anda dengan OpenTelemetry. Anda dapat melihat trace ini di platform observabilitas yang sudah Anda miliki. Gunakan trace tersebut untuk men-debug permintaan yang gagal atau lambat, melacak penggunaan token dan "latency" (latensi), serta membangun eval dari lalu lintas nyata. Anda juga dapat melihat setiap permintaan di dalam trace aplikasi Anda sendiri, yang ditautkan ke pengguna atau fitur yang mengirimkannya.

OpenTelemetry adalah standar netral vendor yang didukung oleh sebagian besar platform observabilitas. Trace (jejak) adalah catatan lengkap dari satu permintaan yang melewati sistem Anda. Span (rentang) adalah satu langkah dalam sebuah trace, seperti permintaan model atau penggunaan alat. API dan SDK menggunakan atribut dari konvensi semantik GenAI, sehingga platform yang mendukung konvensi tersebut dapat mengenali span tanpa penyiapan tambahan.

Memulai

Anda dapat menyiapkan tracing SDK, tracing API, atau keduanya. Siapkan keduanya untuk melihat span SDK dan API dari sebuah permintaan dalam satu trace, seperti pada contoh trace. Untuk permintaan ke Claude Platform on AWS, span API berada di trace-nya sendiri sebagai gantinya.

Siapkan tracing SDK

Instal SDK dan daftarkan tracer provider.

Siapkan tracing API

Tambahkan tujuan di Claude Console.

Referensi span

Cari span dan atributnya.

Yang Anda dapatkanTracing SDKTracing APIKeduanya sekaligus
Permintaan Messages API
Permintaan Sessions API
Penggunaan token
Setiap eksekusi model dalam sebuah permintaan
Giliran Managed Agents
Alat server, dijalankan oleh API
Alat klien, dijalankan oleh tool runner
Alat dalam sandbox self-hosted
Permintaan API lainnya, seperti mengunggah file
PengaturanKodeConsoleKeduanya
Izin yang diperlukanTidak adaAdminAdmin
CakupanKlien yang menggunakan SDKKlien apa punKlien apa pun
Dukungan platform cloudSemuaClaude Platform
Claude Platform on AWS		Claude Platform
Claude Platform on AWS

Untuk Claude Code, Agent SDK, atau Cowork, lihat pemantauan Claude Code, observability Agent SDK, atau pemantauan aktivitas Cowork.

Mengirim trace ke platform mitra

Kirim trace ke platform observabilitas apa pun yang menerima OTLP, termasuk mitra berikut:

Arize AI

Platform observabilitas dan evaluasi terpadu untuk AI.

Braintrust

Platform observabilitas aktif untuk agen.

Databricks

Control plane AI terpadu untuk observabilitas dan evaluasi.

Datadog

Observabilitas dan keamanan bertenaga AI.

Grafana Cloud

Platform observabilitas terbuka yang dikelola sepenuhnya.

Honeycomb

Platform observabilitas untuk bentuk baru perangkat lunak.

Langfuse

Platform observabilitas dan evaluasi agen sumber terbuka.

LangSmith

Platform rekayasa agen LangSmith.

New Relic

Platform observabilitas cerdas.

PostHog

Platform lengkap untuk membangun produk yang sukses.

Sentry

Debug kode Anda yang rusak dan agen yang berperilaku tidak semestinya.

Splunk

Amati, evaluasi, dan amankan agen.

Mode konten

Setiap tujuan dan setiap klien SDK memiliki mode konten, yang menentukan apakah span menyertakan prompt dan respons model. Atur mode ini saat Anda menambahkan tujuan atau mengonfigurasi SDK.

  • Metadata only (metadata_only di SDK): Default. Span menyertakan pengidentifikasi, waktu, status, jumlah token, dan teks yang Anda pilih, seperti nama dan deskripsi agen dan alat Anda serta nama server MCP Anda.
  • Full content (content di SDK): Visibilitas paling tinggi. Span menyertakan prompt dan respons model, serta semua yang ada di Metadata only.

Dengan Full content, Anda juga dapat melihat mengapa suatu proses gagal atau lambat, membaca percakapan lengkap, dan membangun eval dari trace nyata. Di referensi span OpenTelemetry, atribut yang menyimpan prompt dan respons ditandai Content.

Jika organisasi Anda memiliki pembatasan penanganan data HIPAA, FERPA, atau K-12 dengan Anthropic, tujuan hanya mengekspor metadata apa pun mode kontennya. Span SDK tidak terpengaruh.

Dengan zero data retention, Anda tetap dapat menggunakan Full content. Untuk permintaan Messages API, API menyimpan konten yang diekspor hanya di memori hingga konten tersebut dikirimkan ke tujuan. Claude Managed Agents tidak memenuhi syarat untuk zero data retention, dan retensi datanya tetap sama saat Anda menggunakan OpenTelemetry.

Batas konten

Dengan Full content, setiap span menampung konten hingga 0,75 MB secara default. Batas ini cukup untuk jendela konteks 200k token berisi teks berbahasa Inggris dan tetap berada di bawah batas permintaan 1 MB yang diterapkan oleh banyak platform observabilitas dan proxy. Jika Anda memilih platform mitra sebagai Provider, Console menetapkan batas yang diterima oleh platform tersebut.

Ketika konten melebihi batas, SDK atau API memendekkan konten tersebut dan mengatur anthropic.content.truncated ke true. Span permintaan menghapus prompt sistem dan pesan paling awal terlebih dahulu, dan span alat menghapus blok mulai dari akhir hasil. Gambar dan dokumen hanya muncul sebagai jenisnya.

Ubah batas dalam kasus berikut:

  • Platform observabilitas Anda menerima payload yang lebih besar: Naikkan atau hapus batas agar prompt dan respons yang panjang tetap utuh. Jendela konteks 1M token yang terisi penuh membutuhkan sekitar 4 MB.
  • Platform observabilitas Anda atau proxy di depannya menolak permintaan berukuran besar: Turunkan batas.

Di SDK, atur traces.max_content_bytes. Di Console, atur Content mode ke Full content saat Anda menambahkan tujuan, lalu atur Maximum content size in MB di bagian Advanced settings.

Contoh trace dan cara membacanya

Permintaan Messages API

Di bawah span API dari permintaan yang membuat pesan, API menambahkan span untuk setiap permintaan model dan span alat untuk setiap penggunaan server tool atau alat konektor MCP yang dijalankan API.

Dalam contoh ini, aplikasi Anda memanggil tool runner, helper SDK yang menjalankan alat Anda dan mengirimkan hasilnya kembali ke Claude. Setiap permintaan yang dikirim tool runner memiliki span klien dari SDK dan span server dari API. Span muncul dalam urutan berikut:

  1. Aplikasi Anda memulai span answer_question dan memanggil tool runner Messages di dalamnya (ditampilkan sebagai span anthropic.messages.tool_runner).
  2. Tool runner mengirimkan permintaan pertama (ditampilkan sebagai span klien anthropic.messages.create pertama dan span di bawahnya). Dalam permintaan ini, API menjalankan alat pencarian web di antara dua permintaan model.
  3. Dalam permintaan model kedua, model meminta untuk menggunakan alat kustom get_weather, sehingga permintaan pertama berakhir.
  4. Tool runner menjalankan get_weather (ditampilkan sebagai span anthropic.custom_tool_use get_weather).
  5. Tool runner mengirimkan permintaan kedua dengan hasil alat (ditampilkan sebagai span klien anthropic.messages.create kedua dan span di bawahnya).
  6. Dalam permintaan kedua, model memberikan jawaban akhir.
answer_questionyour codeIt starts the trace.anthropic.messages.tool_runnerSDKIt starts with its parent and runs for most of it.anthropic.messages.createCLIENTSDKIt starts with its parent and runs for about half of it.asks to use a toolanthropic.messages.createSERVERAPIIt starts with its parent and ends with its parent.anthropic.model_requestAPIIt starts with its parent and runs for about a third of it.anthropic.tool_use web_searchAPIIt starts after the span before it and runs for a short part of it.the API runs the toolanthropic.model_requestAPIIt starts after the span before it and ends with its parent.anthropic.custom_tool_use get_weatherSDKIt starts after the span before it and runs for a short part of it.runs your toolanthropic.messages.createCLIENTSDKIt starts after the span before it and ends with its parent.final answeranthropic.messages.createSERVERAPIIt starts with its parent and ends with its parent.anthropic.model_requestAPIIt starts with its parent and ends with its parent.

SDK di aplikasi Anda memancarkan span anthropic.messages.tool_runner, span anthropic.custom_tool_use, dan span klien dari setiap permintaan. Untuk mendapatkan span ini, siapkan tracing SDK.

Setiap permintaan memiliki penggunaan tokennya di beberapa span-nya. Untuk menghitung setiap token sekali saja, lihat Penghitungan token.

Dengan Full content, span server anthropic.messages.create berisi prompt dan respons. Prompt sistem ada di gen_ai.system_instructions, pesan-pesan dari permintaan di gen_ai.input.messages, dan respons di gen_ai.output.messages.

Untuk setiap span dan atributnya, lihat referensi span OpenTelemetry.

Sesi Managed Agents

Sebuah sesi memiliki span untuk setiap permintaan Sessions API dan span giliran untuk setiap giliran agen. Giliran yang dimulai oleh sebuah permintaan merupakan anak dari span permintaan tersebut. Sebuah giliran berisi span untuk setiap permintaan model dan setiap alat yang dijalankan oleh API, kecuali dalam kasus yang tercantum dalam referensi span alat. Giliran juga berisi span untuk setiap evaluasi hasil.

Contoh ini mengikuti satu permintaan chat, di mana aplikasi Anda mengirim pesan ke sebuah sesi dan menjalankan alat kustom. Trace tersebut memiliki span dari aplikasi Anda dan dari API, dengan urutan berikut:

  1. Aplikasi Anda menerima permintaan POST /chat dari pengguna.
  2. Aplikasi Anda memulai session tool runner dari SDK, yang mencantumkan dan melakukan streaming event sesi (ditampilkan sebagai span anthropic.sessions.events.stream dan anthropic.sessions.events.list).
  3. Aplikasi Anda mengirim pesan pengguna ke sesi dengan memanggil sessions.events.send.
  4. Sebuah giliran dimulai dan mencakup permintaan model, penggunaan alat bash, dan giliran pada thread lain (ditampilkan sebagai span anthropic.session.turn pertama dan span di bawahnya).
  5. Model meminta untuk menggunakan alat kustom list_issues, sehingga giliran berakhir dengan stop reason requires_action.
  6. Session tool runner menjalankan list_issues (ditampilkan sebagai span anthropic.custom_tool_use list_issues) dan mengirim hasilnya dengan memanggil sessions.events.send.
  7. Giliran kedua dimulai dengan hasil alat (ditampilkan sebagai span anthropic.session.turn terakhir).
POST /chatSERVERyour codeIt starts the trace.anthropic.sessions.events.streamCLIENTSDKIt starts with its parent and ends with its parent.anthropic.sessions.events.streamSERVERAPIIt starts with its parent and ends with its parent.anthropic.sessions.events.listCLIENTSDKIt starts while the span before it runs and runs for a short part of it.anthropic.sessions.events.listSERVERAPIIt starts early in its parent and runs for most of it.anthropic.sessions.events.sendCLIENTSDKIt starts after the span before it and runs for a short part of it.sends a user messageanthropic.sessions.events.sendSERVERAPIIt starts early in its parent and runs for most of it.anthropic.session.turnAPIIt starts late in its parent and runs past the end of its parent.stop reason requires_actionanthropic.model_requestAPIIt starts early in its parent and runs for a short part of it.anthropic.tool_use bashAPIIt starts after the span before it and runs for a short part of it.gen_ai.tool.name = bashanthropic.session.turnAPIIt starts after the span before it and runs for a short part of it.on another threadanthropic.model_requestAPIIt starts early in its parent and runs for most of it.anthropic.model_requestAPIIt starts after the span before it and ends with its parent.anthropic.custom_tool_use list_issuesSDKIt starts after the span before it and runs for a short part of it.runs your toollist_issuesyour codeIt starts early in its parent and runs for most of it.anthropic.sessions.events.sendCLIENTSDKIt starts after the span before it and runs for a short part of it.sends the tool resultanthropic.sessions.events.sendSERVERAPIIt starts early in its parent and runs for most of it.anthropic.session.turnAPIIt starts late in its parent and runs past the end of its parent.anthropic.model_requestAPIIt starts early in its parent and runs for most of it.

SDK di aplikasi Anda memancarkan span anthropic.custom_tool_use dan span klien dari setiap permintaan. Untuk mendapatkan span ini, siapkan tracing SDK.

Span dari sebuah sesi dapat berada di beberapa trace, misalnya ketika Anda mengirim permintaan berikutnya dari root trace baru. Dengan multiagent aktif, sebuah sesi juga dapat memiliki beberapa thread. Untuk menemukan span yang Anda perlukan, kelompokkan berdasarkan ID.

  • Satu thread: Kelompokkan span berdasarkan gen_ai.conversation.id, yang berisi ID thread sesi. Urutkan berdasarkan waktu mulai untuk membaca thread sebagai transkrip.
  • Seluruh sesi, dengan semua thread-nya: Kelompokkan span berdasarkan anthropic.session.id, lintas trace.

Dengan Full content, Anda dapat membaca konten sebuah sesi dari span-nya.

  • Untuk membaca konten sebuah giliran, gunakan span giliran-nya. Prompt sistem ada di gen_ai.system_instructions pada span giliran pertama sebuah thread, input di gen_ai.input.messages (pesan dan hasil alat Anda, event system.message, dan pesan dari thread lain), dan output di gen_ai.output.messages (pesan agen, penggunaan alat, dan hasil alat).
  • Untuk melihat argumen dan hasil dari penggunaan alat, baca span alat-nya. Argumen ada di gen_ai.tool.call.arguments, dan hasilnya ada di anthropic.tool_result.content.

Untuk setiap span dan atributnya, lihat referensi span OpenTelemetry.

Penghitungan token

Untuk menghitung setiap token sekali saja, jumlahkan span dari hanya satu sumber untuk setiap permintaan. Ketika permintaan Messages API memiliki span SDK dan span API, jumlahkan span API-nya. Keduanya bernama anthropic.messages.create, jadi bedakan berdasarkan jenisnya: span SDK adalah CLIENT dan anaknya, span API, adalah SERVER.

Untuk setiap sumber, jumlahkan hanya span berikut, karena beberapa atribut penggunaan berulang di lebih dari satu tingkat span API:

  • Span SDK: Jumlahkan span anthropic.messages.create. Jika sebuah permintaan memiliki compaction, tambahkan juga anthropic.usage.compaction.input_tokens dan anthropic.usage.compaction.output_tokens dari span tersebut, karena atribut gen_ai.usage.* tidak mencakup token compaction. Jika model fallback melayani sebuah permintaan, span-nya hanya memiliki penggunaan dari model yang melayani respons.
  • Span API dari permintaan Messages API: Jumlahkan span anthropic.messages.create atau span anthropic.model_request-nya, bukan keduanya. Jika sebuah permintaan memiliki compaction, tambahkan juga span anthropic.compaction-nya. Jangan tambahkan juga atribut anthropic.usage.compaction.* dari span anthropic.messages.create, karena atribut tersebut berisi token yang sama.
  • Span API dari sesi Managed Agents: Jumlahkan span anthropic.model_request dan anthropic.session.outcome_evaluation.

Span dapat tiba lebih dari sekali, misalnya ketika pengiriman dicoba ulang. Jika platform observabilitas Anda tidak menghapus duplikat, hitung setiap span sekali berdasarkan trace ID dan span ID-nya.

gen_ai.usage.input_tokens sudah mencakup token yang dibaca dari dan ditulis ke cache prompt, jadi jangan tambahkan atribut cache ke dalamnya. Untuk semua atribut penggunaan, lihat Penggunaan token.

Was this page helpful?