Usa OpenTelemetry con il Claude SDK

Con OpenTelemetry, il Claude SDK può emettere uno span (intervallo) per ogni richiesta che invia e per ogni uso di uno strumento eseguito dal tool runner. Puoi visualizzare questi span nella tua piattaforma di osservabilità, annidati nelle tue tracce.

L'SDK emette span nella tua applicazione. L'exporter OpenTelemetry della tua applicazione li invia alla tua piattaforma di osservabilità.

1. Installa l'SDK

Installa o aggiorna all'ultima versione del Claude SDK:

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. Registra un tracer provider

Un tracer provider (fornitore di tracer) è l'oggetto OpenTelemetry che crea gli span e li passa al tuo exporter. L'SDK usa il tracer provider registrato dalla tua applicazione, quindi le tue chiamate all'SDK restano invariate. Registralo prima della prima chiamata che vuoi tracciare.

L'esempio seguente registra un tracer provider che stampa ogni span sulla console e poi effettua una chiamata. Usalo per vedere gli span prima di collegare una piattaforma di osservabilità:

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

# Registra un tracer provider che stampa ogni span sulla console.
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)

La console mostra uno span anthropic.messages.create.

3. Invia gli span alla tua piattaforma di osservabilità

Sostituisci l'exporter per console con un exporter OTLP che punta alla tua piattaforma di osservabilità. Per la configurazione nel tuo linguaggio, consulta la documentazione di OpenTelemetry su exporter Python, exporter TypeScript, exporter .NET, exporter Go, configurazione dell'SDK Java, exporter PHP, o exporter Ruby.

4. Configura l'SDK

Usa le opzioni seguenti per decidere cosa includere nei tuoi span e dove inviarli. Puoi impostare un'opzione nel tuo codice oppure, se ne ha una, con la variabile d'ambiente indicata sotto il suo nome.

L'esempio seguente mostra come usare ciascuna opzione:

# Usa un tracer provider specifico e registra il contenuto.
# L'impostazione di open_telemetry sostituisce tutte le variabili d'ambiente ANTHROPIC_OPEN_TELEMETRY*.
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# Disattiva gli span per un singolo client.
quiet_client = Anthropic(open_telemetry=False)

# Imposta un ID di conversazione con with_options(), che restituisce una copia del client.
# with_options() sostituisce l'intera opzione, quindi parti da 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"}],
)

Passaggi successivi

Tracciamento di uno stream

Lo span anthropic.messages.create di uno stream termina quando il tuo codice ha letto l'intero stream o lo ha chiuso, quindi chiudi uno stream che smetti di leggere in anticipo. In modalità contenuto, lo span contiene la risposta del modello solo quando leggi lo stream con messages.stream().

Gli span che avvii mentre leggi uno stream sono fratelli dello span dell'SDK, non suoi figli. Per raggrupparli con la richiesta, avvia un tuo span che racchiuda sia la chiamata sia il ciclo di lettura.

Tracciamento di una sandbox self-hosted di Managed Agents

In una sandbox self-hosted di Managed Agents, è la tua sandbox a eseguire gli strumenti, quindi gli span degli strumenti provengono dall'SDK anziché dall'API. Il worker dell'ambiente degli SDK Python, TypeScript e Go emette uno span per ogni strumento che esegue e per ogni richiesta che invia. Li raggruppa sotto uno span anthropic.environment.work per ogni elemento di lavoro.

Per ottenere questi span:

1. Nel processo che esegue il worker, configura il tracing dell'SDK come nei passaggi da 1 a 4.
2. Consenti il traffico di rete dalla sandbox alla tua piattaforma di osservabilità o all'OpenTelemetry Collector.

Quando il worker invia un risultato dello strumento, lo span dell'API di quella richiesta è annidato sotto il relativo span dell'SDK. Per le richieste che il worker invia a Claude Platform on AWS, invece, gli span dell'API si trovano in tracce separate.

Contesto di traccia e baggage

A ogni richiesta, l'SDK usa il propagatore della tua applicazione per inviare il contesto di traccia all'API in header come traceparent. Se quel propagatore scrive anche il baggage, l'SDK invia inoltre il tuo baggage. Per inviare il contesto di traccia senza baggage, registra solo il propagatore del contesto di traccia W3C.

Per evitare che l'SDK invii questi header, ad esempio quando la strumentazione del tuo client HTTP li invia già, disattiva la propagazione dell'SDK:

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

Mentre l'SDK chiama uno strumento MCP, lo span di strumento dell'SDK è lo span corrente. Alcune librerie client MCP inviano il contesto di traccia al server MCP in _meta, così un server che lo legge può aggiungere i propri span alla tua traccia sotto quello span di strumento. Lo fanno il pacchetto Python mcp dalla versione 2.0 e il pacchetto C# ModelContextProtocol. Gli SDK MCP per TypeScript, Go, Java, Ruby e PHP non lo fanno da soli.

Risoluzione dei problemi

Compatibility