Menggunakan OpenTelemetry dengan Claude API

Dengan OpenTelemetry, Claude API dapat memancarkan Span (rentang) untuk setiap permintaan model dan setiap penggunaan alat yang dijalankannya. Anda dapat melihat span ini di platform observabilitas Anda tanpa mengubah kode Anda.

API memancarkan span untuk permintaan Messages API dan sesi Managed Agents Anda. Untuk menerimanya, tambahkan destination (tujuan) di Claude Console. Tujuan memberi tahu API endpoint OTLP dari platform observabilitas Anda dan cara melakukan autentikasi dengannya.

Yang Anda butuhkan

• Peran admin di organisasi Claude Console, untuk menambahkan dan mengubah tujuan. Dengan peran developer, Anda dapat melihatnya. Jika organisasi Anda berada di Claude Platform on AWS, masuk ke Console melalui AWS Console, seperti yang dijelaskan di Masuk.
• Endpoint OTLP/HTTP yang menerima encoding protobuf di URL HTTPS pada port 443. Jika Anda menjalankan OpenTelemetry Collector sendiri, receiver OTLP/HTTP-nya mendengarkan pada port 4318 secara default. Konfigurasikan receiver untuk menerima HTTPS pada port 443, atau tempatkan load balancer atau reverse proxy di depan Collector.
• Kredensial untuk endpoint, seperti kunci API.

1. Tambahkan tujuan

1. Di Console, buka halaman pengaturan OpenTelemetry organisasi Anda dan klik Add destination.

2. Konfigurasikan tujuan:

   Kolom	Yang dimasukkan
   Provider	Platform observabilitas Anda, atau Custom jika tidak tercantum. Jika Anda memilih platform yang tercantum, Console akan meminta detailnya, seperti kunci API, sebagai pengganti OTLP endpoint URL, Request headers, dan OTLP traces endpoint URL.
   Name	Opsional. Misalnya, "Platform observabilitas Acme."
   OTLP endpoint URL	URL HTTPS dasar dari endpoint OTLP/HTTP platform observabilitas Anda, dengan hostname, bukan alamat IP. URL ini dapat memiliki prefiks path, misalnya https://gateway.example.com/otlp. Jangan tambahkan /v1/traces, karena API akan menambahkannya. Jika Anda menetapkan OTLP traces endpoint URL, API akan menggunakan URL tersebut sebagai gantinya.
   Request headers	Header yang dikirim API bersama setiap permintaan, misalnya header kunci API dari platform observabilitas Anda. Letakkan kredensial hanya di nilai header. Setelah Anda menyimpan, Console tidak menampilkan nilai tersebut lagi.
   Content mode	Metadata only atau Full content. Lihat perbedaan mode konten.
   Workspaces	Workspace yang span-nya diterima oleh tujuan: All, Selected, atau All except. Lihat Pilih workspace untuk tujuan.
   OTLP traces endpoint URL	Opsional, di bawah Advanced settings. URL lengkap endpoint trace platform observabilitas Anda, misalnya https://gateway.example.com/custom/traces. Tetapkan ini ketika platform tersebut menerima trace di URL selain OTLP endpoint URL ditambah /v1/traces. URL ini harus memiliki host yang sama dengan OTLP endpoint URL.
   Maximum content size in MB	Opsional, di bawah Advanced settings jika mode konten adalah Full content. Jumlah konten maksimum yang dikirim API di setiap span. Console mengisinya berdasarkan Provider yang Anda pilih. Ubah nilainya agar sesuai dengan yang diterima platform observabilitas Anda. Biarkan kosong untuk mengirim konten sebanyak yang diizinkan API. Lihat Batas konten.

3. Klik Add destination untuk menyimpan.

4. Klik Test di menu More actions milik tujuan tersebut. Anda akan melihat pesan bahwa span pengujian telah terkirim ke kolektor Anda, atau bagaimana pengiriman gagal (lihat Kesalahan pengiriman).

5. Periksa apakah span anthropic.test telah sampai di platform observabilitas Anda.

Admin API dan CLI

Anda juga dapat menambahkan tujuan melalui Admin API sebagai pengganti Console. Masuk ke CLI sebagai admin, atau gunakan kunci Admin API di ANTHROPIC_API_KEY. Di Claude Platform on AWS, kirim permintaan ke https://aws-external-anthropic.{region}.api.aws sebagai gantinya, ditandatangani dengan kredensial AWS Anda seperti di Membuat permintaan. Di sana, kebijakan IAM Anda menentukan siapa yang dapat mengelola tujuan. Sebuah permintaan hanya dapat menyertakan workspace dari akun AWS Anda di Region tersebut.

client = anthropic.Anthropic()

destination = client.beta.organization.telemetry_destinations.create(
    endpoint_url="https://gateway.example.com/otlp",
    headers={"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
    traces={"content_mode": "metadata_only"},
    workspaces={"type": "all"},
)

print(destination.id)

Permintaan create menerima pengaturan Console kecuali Provider, jadi masukkan sendiri URL endpoint dan header platform observabilitas Anda. Atur traces.max_content_bytes, dalam byte, agar sesuai dengan yang diterima platform observabilitas Anda (lihat Batas konten). Untuk mencantumkan, mengubah, atau menghapus tujuan, atau untuk menambahkan atau menghapus satu workspace, gunakan metode lain dari API tujuan telemetri.

2. Pilih workspace untuk tujuan

Tujuan menerima span dari workspace yang dicakupnya. Pilih workspace tersebut saat Anda menambahkan tujuan. Untuk Workspaces, pilih salah satu dari berikut ini:

• All: Setiap workspace di organisasi, termasuk Default Workspace dan workspace yang dibuat kemudian.
• Selected: Hanya workspace yang Anda pilih.
• All except: Seperti All, tetapi tanpa workspace yang Anda pilih.

Untuk Selected atau All except, pilih workspace di kotak pencarian yang muncul di bawah opsi. Untuk mengubah workspace suatu tujuan nanti, buka menu More actions miliknya di halaman pengaturan OpenTelemetry saat filter Workspace menampilkan All. Klik Edit, lalu pilih opsi Workspaces lain atau ubah workspace di kotak pencarian.

Jika Anda memiliki peran developer di organisasi dan peran Workspace Admin di sebuah workspace, Anda dapat menambahkan workspace tersebut ke tujuan Selected atau menghapusnya dari tujuan itu. Atur filter Workspace ke workspace tersebut, lalu buka menu More actions tujuan. Di Claude Platform on AWS, Console tidak memiliki peran Workspace Admin. Di sana, kebijakan IAM Anda yang menentukan siapa yang dapat menambahkan workspace ke tujuan atau menghapusnya dari tujuan itu.

API mengirimkan span ke setiap tujuan aktif yang mencakup workspace tempat permintaan atau sesi berjalan.

3. Periksa bahwa span tiba

1. Di Console, pilih workspace yang dicakup oleh tujuan tersebut dan kirim permintaan Messages API di playground. Anda juga dapat mengirim permintaan Messages API dari aplikasi Anda atau memulai sesi Managed Agents di workspace tersebut. Untuk memulai sesi, Anda dapat mengikuti langkah-langkah di Memulai dengan Claude Managed Agents.
2. Di Console, pada halaman pengaturan OpenTelemetry, periksa bahwa kolom Delivery dari tujuan menampilkan Healthy. Ini dapat memakan waktu sekitar satu menit.
3. Di platform observabilitas Anda, filter berdasarkan service.name = claude-platform untuk menemukan span dari permintaan tersebut.

Jika kolom menampilkan Failing, arahkan penunjuk ke atasnya untuk melihat kesalahan terakhir. Untuk menemukan kemungkinan penyebabnya, lihat Kesalahan pengiriman.

4. Hubungkan span API ke trace Anda sendiri

Secara default, span API dari permintaan Messages API atau sesi Managed Agents berada di trace-nya sendiri. Hubungkan span tersebut ke trace aplikasi Anda, sehingga span tersebut bersarang di bawah span Anda sendiri.

API membaca konteks trace dari setiap permintaan dari header traceparent W3C. Jika flag sampled di header tersebut nonaktif, API tidak memancarkan span dari permintaan tersebut maupun span di bawahnya. Claude Platform on AWS belum mendukung header ini. Span untuk permintaan yang Anda kirim ke platform tersebut selalu memulai trace-nya sendiri, bahkan ketika flag sampled nonaktif.

from opentelemetry import trace

tracer = trace.get_tracer("my-service")

with tracer.start_as_current_span("summarize_issues"):
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    )

import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

headers = {
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
    "anthropic-beta": "managed-agents-2026-04-01",
    "content-type": "application/json",
}
# Salin konteks trace dari span aktif ke dalam header permintaan.
TraceContextTextMapPropagator().inject(headers)

httpx2.post(
    f"https://api.anthropic.com/v1/sessions/{os.environ['SESSION_ID']}/events",
    headers=headers,
    json={
        "events": [
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    },
)

Messages API juga meneruskan trace ke server MCP Anda saat Anda menghubungkannya dengan konektor MCP, sehingga server tersebut dapat menempatkan span-nya sendiri di bawah span API. Setiap permintaan dan notifikasi yang dikirim API ke server MCP Anda memiliki traceparent W3C di params._meta. Dalam permintaan tools/call, traceparent tersebut merujuk span anthropic.mcp_tool_use dari penggunaan alat tersebut. Dalam pesan lainnya, traceparent tersebut merujuk span anthropic.messages.create. Untuk permintaan yang tidak di-trace oleh API, seperti permintaan yang header traceparent-nya memiliki flag sampled tidak aktif, API tidak mengirimkan traceparent.

Langkah selanjutnya

Pengiriman dan kesehatan

Aturan berikut berlaku untuk span yang dikirim API ke tujuan Anda.

• Setidaknya sekali: Sebuah tujuan dapat menerima span yang sama lebih dari sekali. Untuk menghapus duplikat, gunakan trace ID dan span ID.
• Upaya terbaik: Sebuah span dapat hilang sebelum dikirimkan. API tidak dapat mengirim ulang span yang hilang.
• Kompresi: API mengompresi permintaan pertama dari setiap pengiriman dengan gzip dan mengatur header Content-Encoding: gzip. Jika endpoint Anda menjawab permintaan tersebut dengan respons 400 atau 415, API segera mengirim ulang span yang sama tanpa kompresi.
• Percobaan ulang: API mencoba pengiriman lagi nanti, dalam jumlah terbatas, setelah timeout, kegagalan koneksi, TLS, atau DNS, atau respons 408, 429, atau 5xx. API tidak mencoba ulang kegagalan lainnya.
• Timeout: Untuk setiap permintaan, endpoint Anda harus menyelesaikan handshake TLS dalam 5 detik dan mengirim header respons dalam 5 detik. Setiap pengiriman mengalami timeout setelah total 10 detik, termasuk pengiriman ulang tanpa kompresi.
• User agent: Setiap permintaan memiliki header User-Agent: Claude-Platform.

Kolom Delivery menampilkan status setiap tujuan. Status dapat terlambat hingga satu menit.

API menonaktifkan tujuan ketika:

• Endpoint mengirimkan redirect 3xx.
• Nama host endpoint di-resolve ke alamat IP yang tidak publik.
• Semua pengiriman gagal selama 24 jam.

API tidak mengirim span ke tujuan yang dinonaktifkan. Untuk melanjutkan ekspor, perbaiki penyebabnya. Kemudian, dengan filter Workspace di halaman pengaturan OpenTelemetry menampilkan All, klik Enable di menu More actions milik tujuan tersebut. Ekspor dimulai lagi dalam sekitar satu menit.

Untuk mengubah sebuah tujuan, buka menu More actions miliknya saat filter Workspace menampilkan All. Kemudian klik Edit, Disable, Enable, atau Delete. Jika Anda mengubah host dari OTLP endpoint URL, masukkan kembali nilai header. Jika tujuan memiliki OTLP traces endpoint URL, berikan host baru yang sama, atau kosongkan.

Batas

Pemecahan masalah

Error pengiriman

Ketika pengiriman gagal, kolom Delivery menampilkan Failing. Arahkan pointer ke atasnya untuk melihat error-nya, lalu temukan kemungkinan penyebabnya:

Compatibility