Intelligenza artificiale
Il 14 ottobre 2026 Anthropic ha lanciato in beta l’export OpenTelemetry per la Claude Platform. Le richieste alla Messages API e le sessioni di Claude Managed Agents si possono così tracciare nel backend di osservabilità che si usa già, come indicano le note di rilascio della Claude Platform. L’SDK Claude emette span in Python, TypeScript, C#, Go, Java, PHP e Ruby; per ottenere gli span dall’API basta aggiungere una destinazione OpenTelemetry nella Claude Console.
A cosa servono le tracce e perché OpenTelemetry
Secondo la documentazione di Anthropic su OpenTelemetry, le tracce servono a fare debug di richieste fallite o lente, a seguire spesa di token e latenza e a costruire valutazioni (eval) a partire dal traffico reale. Ogni richiesta può inoltre comparire dentro le tracce della propria applicazione, collegata all’utente o alla funzione che l’ha generata.
Anthropic ricorda che OpenTelemetry è uno standard neutrale rispetto ai fornitori, supportato dalla maggior parte delle piattaforme di osservabilità. API e SDK usano gli attributi delle convenzioni semantiche GenAI: le piattaforme che le supportano riconoscono gli span senza configurazioni aggiuntive. La funzione è in beta sia su Claude API sia su Claude Platform on AWS e copre Messages API e Claude Managed Agents.
Due strade: tracing dell’SDK e tracing dell’API
Si può attivare il tracing dell’SDK, quello dell’API o entrambi. Con entrambi, gli span SDK e API di una richiesta finiscono in un’unica traccia; per le richieste a Claude Platform on AWS, invece, gli span API restano in tracce separate.
| Tracing SDK | Tracing API | |
|---|---|---|
| Dove si configura | Nel codice | Nella Console |
| Permesso richiesto | Nessuno | Ruolo admin |
| Copertura | Client che usano l’SDK | Qualsiasi client |
| Piattaforma cloud | Qualsiasi | Claude Platform e Claude Platform on AWS |
Il tracing API copre le richieste Messages API e Sessions API, l’uso dei token, ogni esecuzione del modello, i turni di Managed Agents e i tool server eseguiti dall’API. Gli span dei tool client eseguiti dal tool runner sono invece emessi dall’SDK, quindi richiedono il tracing SDK.
Dove mandare le tracce
Le tracce possono andare a qualsiasi piattaforma che accetti OTLP. Anthropic elenca come partner Arize AI, Braintrust, Databricks, Datadog, Grafana Cloud, Honeycomb, Langfuse, LangSmith, New Relic, PostHog, Sentry e Splunk. Per ritrovare gli span nella piattaforma scelta si filtra su service.name = claude-platform.
Prompt e risposte: cosa finisce nelle tracce
Secondo la documentazione, ogni destinazione e ogni client SDK ha una modalità di contenuto, che stabilisce se gli span includono prompt e risposte.
- Metadata only (predefinita): identificatori, tempi, stato, conteggi di token e i testi scelti dall’utente, come nomi e descrizioni di agenti e tool e nomi dei server MCP.
- Full content: quanto sopra, più prompt e risposte del modello, utile per capire perché una run è fallita o lenta, leggere le conversazioni complete e creare eval.
Se l’organizzazione ha con Anthropic una restrizione HIPAA, FERPA o K-12 sul trattamento dei dati, le destinazioni esportano solo metadati a prescindere dalla modalità scelta; gli span dell’SDK non sono toccati. Con la zero data retention si può usare Full content: per le richieste Messages API l’API tiene il contenuto esportato solo in memoria fino alla consegna. Claude Managed Agents non è idoneo alla zero data retention e la sua conservazione dei dati non cambia con OpenTelemetry. Dopo la consegna, i dati restano al servizio scelto, fuori da Anthropic, con le sue regole di conservazione e accesso.
In Full content ogni span contiene per impostazione predefinita fino a 0,75 MB di contenuto, abbastanza per una finestra di contesto da 200k token di testo inglese. Oltre il limite il contenuto viene accorciato e l’attributo anthropic.content.truncated vale true. Una finestra da 1M token richiede circa 4 MB. Il limite si cambia con traces.max_content_bytes nell’SDK o con «Maximum content size» nella Console.
Come si configura una destinazione
Secondo la guida al tracing dell’API, servono tre cose:
- il ruolo admin in un’organizzazione della Claude Console;
- un endpoint OTLP/HTTP con codifica protobuf, raggiungibile a un URL HTTPS sulla porta 443;
- le credenziali dell’endpoint, per esempio una chiave API.
Nella Console si apre la pagina delle impostazioni OpenTelemetry dell’organizzazione e si sceglie il provider (o Custom), l’URL base dell’endpoint senza /v1/traces, gli header di richiesta con le credenziali, la modalità di contenuto e i workspace coperti: tutti, solo quelli selezionati o tutti tranne alcuni. Il pulsante Test invia uno span anthropic.test per verificare la consegna. La stessa operazione si può fare con l’Admin API, tramite client.beta.organization.telemetry_destinations.create, o da CLI. Ogni organizzazione può avere al massimo 10 destinazioni, comprese quelle disabilitate.
Collegare gli span API alle proprie tracce
Per impostazione predefinita gli span API stanno in tracce proprie. Per annidarli sotto gli span dell’applicazione l’API legge l’header W3C traceparent: se il flag sampled è spento, non emette gli span della richiesta. Claude Platform on AWS non supporta ancora questo header, quindi lì gli span partono sempre da una traccia nuova.
Con il connettore MCP, la Messages API passa il contesto di traccia al server MCP tramite traceparent in params._meta, così il server può mettere i propri span sotto quelli dell’API.
Affidabilità della consegna
Secondo Anthropic, la consegna degli span è «at least once», quindi possono arrivare duplicati da eliminare con trace ID e span ID, ed è «best effort»: uno span può andare perso prima della consegna e non viene reinviato. L’API disabilita una destinazione in tre casi:
- l’endpoint risponde con un redirect 3xx;
- l’hostname risolve a un indirizzo IP non pubblico;
- tutte le consegne falliscono per 24 ore.
Per riprendere l’export bisogna risolvere la causa e riabilitare la destinazione dalla Console; l’esportazione riparte entro circa un minuto.
