ClaudeDevs ha annunciato il 14 ottobre 2026 la beta pubblica delle tracce OpenTelemetry per Claude Platform: il tracciamento riguarda le richieste a Messages API, le sessioni Claude Managed Agents e gli SDK di Claude. L’annuncio definisce l’ambito della funzione; Anthropic la classifica come beta e la lega all’accordo con il cliente, compresa la sezione Beta Services dei Service Specific Terms. La panoramica ufficiale ne descrive condizioni e limiti.
Una traccia OpenTelemetry è una sequenza di span: registrano le singole attività che compongono una richiesta e aiutano a seguirne il percorso. La scelta pratica è fra tracciare ciò che accade nell’applicazione con l’SDK e aggiungere la visibilità sulle attività lato Anthropic configurando una destinazione in Claude Console.
Due percorsi, due punti di osservazione
Il tracing SDK registra attività dal lato dell’applicazione, comprese quelle degli strumenti eseguiti dal tool runner del client. Il tracing API configurato in Console aggiunge span per le singole esecuzioni del modello, le sessioni Claude Managed Agents e gli strumenti eseguiti lato server. Entrambi coprono le richieste a Messages API e l’uso di token, ma osservano parti diverse del flusso.
| Criterio | Tracing SDK | Tracing API in Console |
| Dove si configura | Nell’applicazione, registrando un provider OpenTelemetry e configurando un esportatore. | In Claude Console, aggiungendo una destinazione di osservabilità. |
| Permessi | Non richiede un ruolo speciale in Console. | Per aggiungere o modificare destinazioni serve il ruolo di amministratore dell’organizzazione. |
| Attività osservate | Attività lato applicazione, compresi gli strumenti eseguiti dal tool runner del client. | Esecuzioni dei modelli, turni di Claude Managed Agents e strumenti eseguiti lato server. |
| Modifiche al codice dell’app | La strumentazione va configurata nell’applicazione. | L’esportazione degli span lato API si configura in Console, senza modificare il codice dell’applicazione. |
Se vuoi seguire il comportamento del client e dei suoi strumenti, l’SDK è il percorso pertinente. Per osservare anche ciò che avviene nei servizi Anthropic, serve la destinazione API in Console; la configurazione richiede un amministratore. I due percorsi possono essere combinati: quando la propagazione del contesto è configurata, gli span dell’SDK possono collegarsi agli span API in una singola traccia per le richieste supportate di Claude Platform.
Configurazione dell’SDK e richieste in streaming
Con l’SDK, registra il provider OpenTelemetry prima della prima richiesta che vuoi tracciare: farlo dopo significa che le chiamate precedenti non avranno la strumentazione richiesta. Una richiesta in streaming genera uno span che termina quando l’applicazione ha letto o chiuso il flusso. In modalità Full content, i dati della risposta vengono inclusi quando lo stream è letto con messages.stream(). La guida SDK di Anthropic avverte anche che, durante la beta, opzioni e schema degli span possono cambiare in modo incompatibile; fissare la versione dell’SDK permette di controllare quando adottare le modifiche.
La guida elenca il tracing SDK in beta per Claude API, Claude Platform su AWS, Amazon Bedrock, Google Cloud e Microsoft Foundry. Il tracing API configurato in Console è invece indicato per Claude API e Claude Platform su AWS.
Metadati o contenuto completo
Per impostazione predefinita, l’esportazione contiene solo metadati. La modalità Full content può aggiungere prompt e risposte, quindi la scelta determina quali contenuti raggiungono la destinazione di osservabilità. È configurabile separatamente per ciascuna destinazione e per ciascun client SDK; il servizio di osservabilità scelto applica i propri controlli di accesso e conservazione.
Anthropic imposta per ogni span Full content un limite predefinito di 0,75 MB. Se il contenuto supera il limite configurato, viene accorciato e lo span riceve l’attributo anthropic.content.truncated=true. Nelle tracce delle richieste vengono rimossi prima il prompt di sistema e i messaggi più vecchi; negli span degli strumenti vengono eliminati i blocchi dalla fine del risultato. Immagini e documenti sono rappresentati come tipi di contenuto, non come contenuto leggibile.
Ci sono anche restrizioni specifiche. Per le destinazioni Console, le organizzazioni soggette a vincoli di gestione dei dati HIPAA, FERPA o K-12 con Anthropic esportano solo metadati, qualunque modalità sia stata selezionata; la restrizione non si applica agli span SDK. Con zero data retention, Full content resta disponibile per il tracing di Messages API e Anthropic conserva i contenuti esportati solo in memoria fino alla consegna. Claude Managed Agents non rientra nell’idoneità allo zero data retention e OpenTelemetry non ne modifica la conservazione.
Destinazione API: formato e limiti
La destinazione API deve accettare OTLP/HTTP protobuf, il formato di esportazione OpenTelemetry, tramite HTTPS sulla porta 443. L’URL di base deve indicare il servizio ricevente: se non specifichi un endpoint separato per le tracce, Anthropic aggiunge /v1/traces. Ogni destinazione può includere fino a 1.000 workspace e 20 intestazioni di richiesta; un’organizzazione può configurarne fino a 10.
Anche i tempi di risposta sono distinti: l’handshake TLS deve terminare entro 5 secondi, le intestazioni di risposta devono arrivare entro 5 secondi e ogni consegna scade dopo 10 secondi complessivi. Sono condizioni da considerare quando si sceglie e configura il ricevitore. La guida API di Anthropic descrive formato, percorso, limiti delle destinazioni e comportamento delle consegne.
Le tracce non sono un registro completo dei consumi
Anthropic descrive la consegna come best effort e at least once: alcuni span possono andare persi, mentre altri possono arrivare duplicati. La documentazione indica la Usage API per il monitoraggio completo dell’utilizzo delle API, non l’esportazione delle tracce.
Claude Code ha una documentazione di monitoraggio separata; la beta qui descritta riguarda Messages API, Claude Managed Agents e SDK di Claude Platform. La guida di Anthropic per Claude Code tratta quel percorso distinto.
