Menggunakan OpenTelemetry dengan Claude SDK

Dengan OpenTelemetry, Claude SDK dapat memancarkan Span (rentang) untuk setiap permintaan yang dikirimnya dan setiap penggunaan alat yang dijalankan oleh tool runner. Anda dapat melihat span ini di platform observabilitas Anda, bersarang di dalam trace Anda sendiri.

SDK memancarkan span di aplikasi Anda. "Exporter" (pengekspor) OpenTelemetry aplikasi Anda mengirimkannya ke platform observabilitas Anda.

1. Instal SDK

Instal atau tingkatkan ke versi terbaru Claude SDK:

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. Daftarkan tracer provider

Tracer provider (penyedia tracer) adalah objek OpenTelemetry yang membuat span dan meneruskannya ke exporter Anda. SDK menggunakan tracer provider yang didaftarkan oleh aplikasi Anda, sehingga panggilan SDK Anda tetap sama. Daftarkan tracer provider sebelum panggilan pertama yang ingin Anda telusuri.

Contoh berikut mendaftarkan tracer provider yang mencetak setiap span ke konsol, lalu melakukan satu panggilan. Gunakan contoh ini untuk melihat span sebelum Anda menghubungkan platform observabilitas:

from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# Daftarkan tracer provider yang mencetak setiap span ke konsol.
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

client = Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)

Konsol menampilkan satu span anthropic.messages.create.

3. Kirim span ke platform observabilitas Anda

Ganti exporter konsol dengan exporter OTLP yang mengarah ke platform observabilitas Anda. Untuk penyiapan dalam bahasa Anda, lihat dokumentasi OpenTelemetry tentang exporter Python, exporter TypeScript, exporter .NET, exporter Go, konfigurasi SDK Java, exporter PHP, atau exporter Ruby.

4. Konfigurasikan SDK

Gunakan opsi berikut untuk menentukan apa yang masuk ke dalam span Anda dan ke mana span tersebut dikirim. Anda dapat mengatur sebuah opsi di dalam kode Anda atau, jika opsi tersebut memilikinya, melalui variabel lingkungan yang tercantum di bawah namanya.

Contoh berikut menunjukkan cara menggunakan setiap opsi:

# Gunakan tracer provider tertentu dan rekam kontennya.
# Mengatur open_telemetry akan menimpa semua variabel lingkungan ANTHROPIC_OPEN_TELEMETRY*.
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# Nonaktifkan span untuk satu klien.
quiet_client = Anthropic(open_telemetry=False)

# Tetapkan ID percakapan dengan with_options(), yang mengembalikan salinan klien.
# with_options() mengganti seluruh opsi, jadi mulailah dari client.open_telemetry.
message = client.with_options(
    open_telemetry={**client.open_telemetry, "conversation_id": "conv_42"}
).messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

Langkah selanjutnya

Penelusuran stream

Span anthropic.messages.create dari sebuah stream berakhir ketika kode Anda telah membaca seluruh stream atau menutupnya, jadi tutuplah stream yang berhenti Anda baca lebih awal. Dalam mode konten, span berisi respons model hanya jika Anda membaca stream dengan messages.stream().

Span yang Anda mulai saat membaca stream adalah saudara (sibling) dari span SDK, bukan turunannya. Untuk mengelompokkannya dengan permintaan, mulailah span Anda sendiri yang mencakup panggilan dan loop pembacaan.

Penelusuran sandbox self-hosted Managed Agents

Dalam sandbox self-hosted Managed Agents, sandbox Anda yang menjalankan alat, sehingga span alat berasal dari SDK, bukan dari API. Environment worker di SDK Python, TypeScript, dan Go memancarkan span untuk setiap alat yang dijalankannya dan setiap permintaan yang dikirimnya. Worker mengelompokkannya di bawah satu span anthropic.environment.work untuk setiap item pekerjaan.

Untuk mendapatkan span ini:

1. Di proses yang menjalankan worker, siapkan tracing SDK seperti pada langkah 1 hingga 4.
2. Izinkan lalu lintas jaringan dari sandbox ke platform observabilitas atau OpenTelemetry Collector Anda.

Ketika worker mengirim hasil tool, span API untuk permintaan tersebut bersarang di bawah span SDK-nya. Untuk permintaan yang dikirim worker ke Claude Platform on AWS, span API berada di trace-nya sendiri sebagai gantinya.

Konteks trace dan baggage

Pada setiap permintaan, SDK menggunakan propagator aplikasi Anda untuk mengirim konteks trace ke API dalam header seperti traceparent. Jika propagator tersebut juga menulis baggage, SDK juga mengirim baggage Anda. Untuk mengirim konteks trace tanpa baggage, daftarkan hanya propagator konteks trace W3C.

Agar SDK tidak mengirim header ini, misalnya ketika instrumentasi klien HTTP Anda sudah mengirimnya, nonaktifkan propagasi SDK:

client = Anthropic(open_telemetry={"propagation": False})

Saat SDK memanggil alat MCP, span alat milik SDK adalah span saat ini. Beberapa pustaka klien MCP mengirim konteks trace ke server MCP di _meta, sehingga server yang membacanya dapat menambahkan span-nya ke trace Anda di bawah span alat tersebut. Paket Python mcp mulai versi 2.0 dan paket C# ModelContextProtocol melakukannya. SDK MCP untuk TypeScript, Go, Java, Ruby, dan PHP tidak melakukannya sendiri.

Pemecahan masalah

Compatibility