Usa OpenTelemetry con la Claude API

Con OpenTelemetry, la Claude API può emettere uno span (intervallo) per ogni richiesta al modello e per ogni uso di uno strumento che esegue. Puoi visualizzare questi span nella tua piattaforma di osservabilità senza modificare il tuo codice.

L'API emette span per le tue richieste alla Messages API e per le sessioni di Managed Agents. Per riceverli, aggiungi una destinazione nella Claude Console. Una destinazione indica all'API l'endpoint OTLP della tua piattaforma di osservabilità e come autenticarsi con esso.

Cosa ti serve

• Il ruolo di amministratore in un'organizzazione della Claude Console, per aggiungere e modificare le destinazioni. Con il ruolo di sviluppatore puoi visualizzarle. Se la tua organizzazione è su Claude Platform on AWS, accedi alla Console tramite la AWS Console, come descritto in Accesso.
• Un endpoint OTLP/HTTP che accetti la codifica protobuf su un URL HTTPS sulla porta 443. Se esegui un tuo OpenTelemetry Collector, il suo receiver OTLP/HTTP è in ascolto sulla porta 4318 per impostazione predefinita. Configura il receiver per accettare HTTPS sulla porta 443, oppure metti un load balancer o un reverse proxy davanti al Collector.
• Credenziali per l'endpoint, come una chiave API.

1. Aggiungi una destinazione

1. Nella Console, apri la pagina delle impostazioni OpenTelemetry della tua organizzazione e fai clic su Add destination.

2. Configura la destinazione:

   Campo	Cosa inserire
   Provider	La tua piattaforma di osservabilità, oppure Custom se non è elencata. Se scegli una piattaforma elencata, la Console richiede i suoi dettagli, come una chiave API, al posto di OTLP endpoint URL, Request headers e OTLP traces endpoint URL.
   Name	Facoltativo. Ad esempio, "Piattaforma di osservabilità di Acme."
   OTLP endpoint URL	L'URL HTTPS di base dell'endpoint OTLP/HTTP della tua piattaforma di osservabilità, con un nome host, non un indirizzo IP. Può avere un prefisso di percorso, ad esempio https://gateway.example.com/otlp. Non aggiungere /v1/traces, perché l'API lo aggiunge. Se imposti un OTLP traces endpoint URL, l'API usa invece quell'URL.
   Request headers	Gli header che l'API invia con ogni richiesta, ad esempio l'header con la chiave API della tua piattaforma di osservabilità. Inserisci le credenziali solo nei valori degli header. Dopo il salvataggio, la Console non mostra più i valori.
   Content mode	Metadata only o Full content. Consulta in cosa differiscono le modalità di contenuto.
   Workspaces	I workspace di cui la destinazione riceve gli span: All, Selected o All except. Consulta Scegli i workspace per una destinazione.
   OTLP traces endpoint URL	Facoltativo, in Advanced settings. L'URL completo dell'endpoint delle trace della tua piattaforma di osservabilità, ad esempio https://gateway.example.com/custom/traces. Impostalo quando la piattaforma riceve le trace a un URL diverso dall'OTLP endpoint URL più /v1/traces. Deve avere lo stesso host dell'OTLP endpoint URL.
   Maximum content size in MB	Facoltativo, in Advanced settings quando la modalità di contenuto è Full content. La quantità massima di contenuto che l'API invia in ogni span. La Console lo compila in base al Provider scelto. Modificalo in base a ciò che accetta la tua piattaforma di osservabilità. Lascialo vuoto per inviare la quantità massima consentita dall'API. Consulta Limiti del contenuto.

3. Fai clic su Add destination per salvare.

4. Fai clic su Test nel menu More actions della destinazione. Vedrai un messaggio che indica che lo span di test è stato consegnato al tuo collector oppure in che modo la consegna non è riuscita (vedi Errori di consegna).

5. Verifica che lo span anthropic.test sia arrivato nella tua piattaforma di osservabilità.

Admin API e CLI

Puoi anche aggiungere una destinazione tramite l'Admin API invece che dalla Console. Accedi alla CLI come amministratore, oppure usa una chiave Admin API in ANTHROPIC_API_KEY. Su Claude Platform on AWS, invia invece le richieste a https://aws-external-anthropic.{region}.api.aws, firmate con le tue credenziali AWS come in Effettuare richieste. In tal caso, la tua policy IAM decide chi può gestire le destinazioni. Una richiesta può includere solo i workspace del tuo account AWS in quella Region.

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)

Una richiesta di creazione accetta le impostazioni della Console tranne Provider, quindi inserisci tu stesso l'URL dell'endpoint e gli header della tua piattaforma di osservabilità. Imposta traces.max_content_bytes, in byte, in base a ciò che la tua piattaforma di osservabilità accetta (vedi Limiti di contenuto). Per elencare, modificare o eliminare le destinazioni, oppure per aggiungere o rimuovere un workspace, usa gli altri metodi dell'API delle destinazioni di telemetria.

2. Scegli i workspace per una destinazione

Una destinazione riceve gli span dei workspace che copre. Sceglili quando aggiungi la destinazione. Per Workspaces, seleziona una delle seguenti opzioni:

• All: Ogni workspace dell'organizzazione, incluso il Default Workspace e i workspace creati in seguito.
• Selected: Solo i workspace che selezioni.
• All except: Come All, ma senza i workspace che selezioni.

Per Selected o All except, seleziona i workspace nella casella di ricerca che appare sotto le opzioni. Per modificare in seguito i workspace di una destinazione, apri il suo menu More actions nella pagina delle impostazioni di OpenTelemetry mentre il filtro Workspace mostra All. Fai clic su Edit, quindi scegli un'altra opzione di Workspaces o modifica i workspace nella casella di ricerca.

Se hai il ruolo di sviluppatore nell'organizzazione e il ruolo Workspace Admin in un workspace, puoi aggiungere quel workspace a una destinazione Selected o rimuoverlo da essa. Imposta il filtro Workspace su quel workspace, quindi apri il menu More actions della destinazione. Su Claude Platform on AWS, la Console non ha il ruolo Workspace Admin. Lì, è la tua policy IAM a decidere chi può aggiungere un workspace a una destinazione o rimuoverlo da essa.

L'API invia gli span a ogni destinazione abilitata che copre il workspace in cui viene eseguita la richiesta o la sessione.

3. Verifica che gli span arrivino

1. Nella Console, seleziona un workspace coperto dalla destinazione e invia una richiesta alla Messages API nel playground. Puoi anche inviare una richiesta alla Messages API dalla tua applicazione o avviare una sessione di Managed Agents in quel workspace. Per avviare una sessione, puoi seguire i passaggi in Inizia con Claude Managed Agents.
2. Nella Console, nella pagina delle impostazioni OpenTelemetry, verifica che la colonna Delivery della destinazione mostri Healthy. Può richiedere circa un minuto.
3. Nella tua piattaforma di osservabilità, filtra per service.name = claude-platform per trovare gli span della richiesta.

Se la colonna mostra Failing, passa il puntatore sopra di essa per vedere l'ultimo errore. Per trovare la causa probabile, consulta Errori di consegna.

4. Collega gli span dell'API alle tue tracce

Per impostazione predefinita, gli span dell'API di una richiesta alla Messages API o di una sessione di Managed Agents si trovano in tracce separate. Collegali alle tracce della tua applicazione, in modo che siano annidati sotto i tuoi span.

L'API legge il contesto di traccia di ogni richiesta dall'header traceparent W3C. Se il flag sampled nell'header è disattivato, l'API non emette lo span della richiesta né gli span sottostanti. Claude Platform on AWS non supporta ancora questo header. Gli span per le richieste che gli invii avviano sempre tracce separate, anche quando il flag sampled è disattivato.

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",
}
# Copia il contesto di traccia dello span attivo negli header della richiesta.
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"}],
            },
        ],
    },
)

La Messages API passa inoltre la traccia al tuo server MCP quando lo colleghi con il connettore MCP, in modo che possa inserire i propri span sotto gli span dell'API. Ogni richiesta e notifica che l'API invia al tuo server MCP ha un traceparent W3C in params._meta. In una richiesta tools/call, fa riferimento allo span anthropic.mcp_tool_use di quell'uso degli strumenti. Negli altri messaggi, fa riferimento allo span anthropic.messages.create. Per una richiesta che l'API non traccia, come una il cui header traceparent ha il flag sampled disattivato, l'API non invia alcun traceparent.

Passaggi successivi

Consegna e stato

Le regole seguenti si applicano agli span che l'API invia alle tue destinazioni.

• Almeno una volta: Una destinazione può ricevere lo stesso span più di una volta. Per rimuovere i duplicati, usa il trace ID e lo span ID.
• Best effort: Uno span può andare perso prima della consegna. L'API non può inviare di nuovo uno span perso.
• Compressione: L'API comprime con gzip la prima richiesta di ogni consegna e imposta l'header Content-Encoding: gzip. Se il tuo endpoint risponde a quella richiesta con una risposta 400 o 415, l'API invia immediatamente di nuovo gli stessi span senza compressione.
• Tentativi: L'API ritenta la consegna in seguito, per un numero limitato di volte, dopo un timeout, un errore di connessione, TLS o DNS, oppure una risposta 408, 429 o 5xx. Non ritenta in caso di altri errori.
• Timeout: Per ogni richiesta, il tuo endpoint deve completare l'handshake TLS entro 5 secondi e inviare gli header di risposta entro 5 secondi. Ogni consegna va in timeout dopo 10 secondi in totale, incluso il nuovo invio senza compressione.
• User agent: Ogni richiesta ha l'header User-Agent: Claude-Platform.

La colonna Delivery mostra lo stato di ciascuna destinazione. Lo stato può avere un ritardo fino a un minuto.

L'API disabilita una destinazione quando:

• L'endpoint invia un reindirizzamento 3xx.
• Il nome host dell'endpoint si risolve in un indirizzo IP non pubblico.
• Tutte le consegne falliscono per 24 ore.

L'API non invia span a una destinazione disabilitata. Per riprendere l'esportazione, correggi la causa. Poi, con il filtro Workspace nella pagina delle impostazioni di OpenTelemetry impostato su All, fai clic su Enable nel menu More actions della destinazione. L'esportazione riprende entro circa un minuto.

Per modificare una destinazione, apri il suo menu More actions mentre il filtro Workspace mostra All. Poi fai clic su Edit, Disable, Enable o Delete. Se modifichi l'host dell'OTLP endpoint URL, inserisci di nuovo i valori degli header. Se la destinazione ha un OTLP traces endpoint URL, assegnagli lo stesso nuovo host oppure svuotalo.

Limiti

Risoluzione dei problemi

Errori di consegna

Quando una consegna non riesce, la colonna Delivery mostra Failing. Passa il puntatore sopra per vedere l'errore, quindi individua la causa probabile:

Compatibility