Introduzione al nuovo supporto OpenTelemetry

Il 14 ottobre Anthropic ha annunciato l’apertura in beta pubblica dell’esportazione di trace OpenTelemetry dalla Claude Platform. Ora le richieste inviate alla Messages API e le sessioni gestite da Claude Managed Agents possono essere inviate, passo per passo, a sistemi di osservabilità come Datadog, Grafana, Langfuse e a tutti gli altri tool che le aziende già utilizzano.

Il vantaggio principale è la possibilità di passare da una “scatola nera” – che mostrava solo tempi di risposta e conteggio di token – a una visualizzazione completa della sequenza di operazioni (trace) compiuta dal modello, con ciascun passaggio rappresentato da uno span.

Che cosa è una trace e uno span?

OpenTelemetry è lo standard aperto che consente al software di raccontare cosa sta facendo. Una trace è il registro completo di una singola richiesta, mentre uno span è un singolo passaggio interno – ad esempio una chiamata al modello o l’uso di uno strumento.

Claude Platform, la suite di API, Console e strumenti di Anthropic per gli sviluppatori, ora offre due modalità per raccogliere queste informazioni: tramite l’SDK integrato nell’applicazione oppure configurando una destinazione nella Console.

Attivazione immediata

Le destinazioni di telemetria si aggiungono direttamente dalla Console di Claude. È necessario avere il ruolo di amministratore dell’organizzazione e fornire un endpoint OTLP/HTTP raggiungibile via HTTPS sulla porta 443. La funzionalità è attualmente in beta.

Che cosa viene tracciato?

La documentazione di Anthropic elenca tre tipologie di eventi tracciati:

    • Richieste alla Messages API
    • Utilizzo di strumenti (tool runner) e sandbox
    • Sessioni di Claude Managed Agents, ovvero agenti che lavorano per ore su un compito (presenti sin dal lancio di aprile).

Gli attributi seguono le convenzioni semantiche GenAI di OpenTelemetry, permettendo alle piattaforme supportive di riconoscere automaticamente gli span senza configurazioni aggiuntive.

Visibilità differenziata

Il tracciamento lato SDK registra le chiamate dal punto di vista dell’applicazione; quello lato API, configurato nella Console, aggiunge il contesto interno di Anthropic. Le due modalità possono essere combinate: in tal caso lo span dell’SDK contiene quello dell’API, formando un’unica trace coerente.

Confronto SDK vs Console

CaratteristicaSDKAPI (Console)
Richieste alla Messages API e Sessions APISìSì
Consumo di tokenSìSì
Ogni singola richiesta al modelloNoSì
Turni di Managed Agents e strumenti lato serverNoSì
Strumenti eseguiti dal tool runner o sandboxSìNo
Permessi richiestiNessunoRuolo admin

Procedura di attivazione

Per l’SDK:

    • Aggiornare la libreria (disponibile per Python, TypeScript, C#, Go, Java, PHP e Ruby).
    • Registrare un tracer provider OpenTelemetry.
    • Sostituire l’esporter di prova con un OTLP verso la propria piattaforma.
    • Le chiamate al client restano invariate.

Per il tracciamento lato API (Console):

    • Aprire le impostazioni OpenTelemetry nella Console e scegliere “Add destination”.
    • Selezionare il provider (o “Custom”) e inserire l’URL base dell’endpoint OTLP/HTTP in HTTPS sulla porta 443, includendo gli header di autenticazione.
    • Scegliere la modalità di contenuto e i workspace da coprire (tutti, selezionati o esclusi).
    • Premere “Test” per inviare uno span di test (anthropic.test) e verificare che la colonna Delivery diventi “Healthy”.
    • Filtrare nella piattaforma di osservabilità con service.name = claude-platform.

Contenuto delle trace: metadata vs full content

Di default le trace non includono prompt e risposte. Ogni destinazione e ogni client SDK offre due modalità di contenuto:

    • metadata only: esporta identificativi, tempi, stati, conteggi di token e nomi di agenti, strumenti e server MCP.
    • full content: aggiunge anche prompt e risposte del modello, utile per diagnosticare errori o lentezze e per analisi basate sul traffico reale.

Tre limitazioni importanti da considerare:

    • Se l’organizzazione ha vincoli HIPAA, FERPA o K‑12, le destinazioni esportano solo i metadati, indipendentemente dalla modalità impostata.
    • Con la “zero data retention” il contenuto completo è mantenuto solo per la Messages API; le Managed Agents non sono idonee a questa modalità.
    • Ogni span è limitato a 0,75 MB per impostazione predefinita (circa 200.000 token di testo inglese). Superato il limite, l’API tronca il contenuto, scartando prima il prompt di sistema e i messaggi più vecchi, segnando lo span con anthropic.content.truncated. Un contesto da un milione di token richiederebbe circa 4 MB.

Piattaforme di osservabilità supportate

Qualsiasi servizio che accetti OTLP è supportato. Anthropic elenca dodici partner con guide dedicate:

    • Arize AI
    • Braintrust
    • Databricks
    • Datadog
    • Grafana Cloud
    • Honeycomb
    • Langfuse
    • LangSmith
    • New Relic
    • PostHog
    • Sentry
    • Splunk

Per altri servizi è possibile utilizzare l’opzione “Custom” o distribuire un OpenTelemetry Collector gestito in proprio.

Collegamento tra trace API e SDK

Le trace dell’API e quelle dell’applicazione possono essere collegate tramite l’header W3C traceparent. L’SDK lo scrive automaticamente se la chiamata parte dentro uno span proprio; chi usa un client diverso deve copiare manualmente l’header nella richiesta. L’API inoltra l’header anche al server MCP collegato, consentendo a componenti come l’MCP Adapter per WordPress di agganciare i propri span sotto quelli di Claude. Nota: se il flag di campionamento nell’header è disattivato, l’API non emetterà gli span.

Affidabilità della beta e limitazioni operative

Anthropic è trasparente sui limiti della beta:

    • La consegna è “best effort” e “at least once”, quindi uno span può andare perso o arrivare più volte (deduplicazione con trace ID e span ID). Per questo le trace non devono essere usate come registro completo del consumo; la Usage API rimane la fonte di verità per la fatturazione.
    • Per il conteggio dei token si evita il doppio conteggio: si somma una sola fonte per richiesta, scegliendo tra gli span dell’SDK o quelli dell’API, mai entrambi. Per le Managed Agents si considerano gli span anthropic.model_request e quelli di valutazione dell’esito.
    • Una destinazione non funzionante viene automaticamente disattivata dall’API se l’endpoint risponde con redirect, risolve a un IP non pubblico o se tutte le consegne falliscono per 24 ore. La riattivazione richiede intervento manuale dalla Console.
    • Limiti operativi: massimo 10 destinazioni per organizzazione, 20 header per destinazione, handshake TLS entro 5 secondi e risposta totale entro 10 secondi.
    • Essendo una beta, i nomi di span, gli attributi e le opzioni dell’SDK possono cambiare. Si consiglia di fissare la versione dell’SDK nelle dipendenze e aggiornare con cautela.

Impatto su Claude Code

Al momento non sono previste modifiche dirette per Claude Code. Il supporto OpenTelemetry rimane limitato a Messages API, Managed Agents e SDK, senza impatto attuale su funzionalità di generazione di codice.

Conclusioni

La beta pubblica di OpenTelemetry su Claude Platform rappresenta un salto qualitativo nella trasparenza operativa per le aziende che integrano i modelli di Anthropic. La possibilità di osservare ogni singola chiamata, di collegare i trace tra SDK e API e di scegliere tra metadata o full content permette di effettuare diagnosi più precise, ottimizzare i costi e rispettare requisiti normativi. Tuttavia, è fondamentale tenere presente le limitazioni di affidabilità, i vincoli di privacy e i parametri tecnici (limiti di dimensione, numero di destinazioni, tempi di handshake) prima di adottare la soluzione in ambienti di produzione.