AmministrazioneOpenTelemetry

OpenTelemetry per la Claude API

Copy page



Traccia le tue richieste alla Messages API, gli usi degli strumenti e le sessioni di Managed Agents con gli span OpenTelemetry del Claude SDK e della Claude API.

La Claude API e l'SDK possono tracciare le tue richieste alla Messages API, gli usi degli strumenti e le sessioni di Managed Agents con OpenTelemetry. Puoi visualizzare queste tracce nella piattaforma di osservabilità che già utilizzi. Usale per eseguire il debug di richieste non riuscite o lente, monitorare la spesa in token e la "latency" (latenza) e creare valutazioni a partire dal traffico reale. Puoi anche vedere ogni richiesta all'interno delle tracce della tua applicazione, collegata all'utente o alla funzionalità che l'ha inviata.

OpenTelemetry è uno standard indipendente dai fornitori supportato dalla maggior parte delle piattaforme di osservabilità. Una trace (traccia) è la registrazione completa di una richiesta attraverso il tuo sistema. Uno span (intervallo) è un singolo passaggio in una traccia, come una richiesta al modello o un uso di uno strumento. L'API e l'SDK usano gli attributi delle convenzioni semantiche GenAI, quindi le piattaforme che supportano le convenzioni possono riconoscere gli span senza configurazioni aggiuntive.

Per iniziare

Puoi configurare il tracciamento dell'SDK, il tracciamento dell'API o entrambi. Configurali entrambi per vedere gli span dell'SDK e dell'API di una richiesta in un'unica traccia, come negli esempi di tracce. Per le richieste a Claude Platform on AWS, gli span dell'API si trovano invece in tracce separate.

Per Claude Code, l'Agent SDK o Cowork, consulta Monitoraggio di Claude Code, Osservabilità dell'Agent SDK o Monitoraggio dell'attività di Cowork.

Inviare le tracce a una piattaforma partner

Invia le tracce a qualsiasi piattaforma di osservabilità che accetti OTLP, inclusi questi partner:

Modalità di contenuto

Ogni destinazione e ogni client dell'SDK ha una modalità di contenuto, che stabilisce se gli span includono i prompt e le risposte del modello. Impostala quando aggiungi una destinazione o configuri l'SDK.

• Metadata only (metadata_only nell'SDK): L'impostazione predefinita. Gli span includono identificatori, tempi, stato, conteggi dei token e il testo che scegli tu, come i nomi e le descrizioni dei tuoi agenti e strumenti e i nomi dei tuoi server MCP.
• Full content (content nell'SDK): La massima visibilità. Gli span includono i prompt e le risposte del modello, oltre a tutto ciò che è incluso in Metadata only.

Con Full content, puoi anche vedere perché un'esecuzione è fallita o è stata lenta, leggere conversazioni complete e creare valutazioni a partire da tracce reali. Nel riferimento degli span OpenTelemetry, gli attributi che contengono prompt e risposte sono contrassegnati con Content.

Se la tua organizzazione ha una restrizione sulla gestione dei dati HIPAA, FERPA o K-12 con Anthropic, le destinazioni esportano solo i metadati, qualunque sia la loro modalità di contenuto. Gli span dell'SDK non sono interessati.

Con la conservazione zero dei dati, puoi comunque usare Full content. Per le richieste alla Messages API, l'API conserva il contenuto esportato solo in memoria finché non lo consegna alla destinazione. Claude Managed Agents non è idoneo alla conservazione zero dei dati e la sua conservazione dei dati rimane invariata quando usi OpenTelemetry.

Limiti del contenuto

Con Full content, ogni span contiene per impostazione predefinita fino a 0,75 MB di contenuto. Questo limite è sufficiente per una finestra di contesto da 200k token di testo in inglese e resta al di sotto del limite di 1 MB per richiesta di molte piattaforme di osservabilità e proxy. Se scegli una piattaforma partner come Provider, la Console imposta un limite accettato dalla piattaforma.

Quando il contenuto supera il limite, l'SDK o l'API lo accorcia e imposta anthropic.content.truncated su true. Negli span delle richieste vengono rimossi per primi il prompt di sistema e i messaggi meno recenti, e negli span degli strumenti vengono rimossi blocchi dalla fine del risultato. Le immagini e i documenti compaiono solo con il loro tipo.

Modifica il limite in questi casi:

• La tua piattaforma di osservabilità accetta payload più grandi: Aumenta o rimuovi il limite per mantenere interi i prompt e le risposte lunghi. Una finestra di contesto da 1M token piena richiede circa 4 MB.
• La tua piattaforma di osservabilità o un proxy posto davanti a essa rifiuta le richieste di grandi dimensioni: Riduci il limite.

Nell'SDK, imposta traces.max_content_bytes. Nella Console, imposta Content mode su Full content quando aggiungi una destinazione, quindi imposta Maximum content size in MB in Advanced settings.

Tracce di esempio e come leggerle

Una richiesta alla Messages API

Sotto lo span dell'API di una richiesta che crea un messaggio, l'API aggiunge uno span per ogni richiesta al modello e uno span di strumento per ogni uso di uno strumento server o di uno strumento del connettore MCP eseguito dall'API.

In questo esempio, la tua applicazione chiama il tool runner, l'helper dell'SDK che esegue i tuoi strumenti e invia i loro risultati a Claude. Ogni richiesta inviata dal tool runner ha uno span client dall'SDK e uno span server dall'API. Gli span compaiono nell'ordine seguente:

1. La tua applicazione avvia lo span answer_question e al suo interno chiama il tool runner di Messages (mostrato come lo span anthropic.messages.tool_runner).
2. Il tool runner invia la prima richiesta (mostrata come il primo span client anthropic.messages.create e gli span sottostanti). In questa richiesta, l'API esegue lo strumento di ricerca web tra due richieste al modello.
3. Nella seconda richiesta al modello, il modello chiede di usare lo strumento personalizzato get_weather, quindi la prima richiesta termina.
4. Il tool runner esegue get_weather (mostrato come lo span anthropic.custom_tool_use get_weather).
5. Il tool runner invia la seconda richiesta con il risultato dello strumento (mostrata come il secondo span client anthropic.messages.create e gli span sottostanti).
6. Nella seconda richiesta, il modello fornisce la risposta finale.

L'SDK nella tua applicazione emette lo span anthropic.messages.tool_runner, lo span anthropic.custom_tool_use e lo span client di ogni richiesta. Per ottenere questi span, configura il tracciamento dell'SDK.

Ogni richiesta riporta il proprio utilizzo di token su diversi dei suoi span. Per contare ogni token una sola volta, consulta Conteggio dei token.

Con Full content, lo span server anthropic.messages.create contiene il prompt e la risposta. Il prompt di sistema si trova in gen_ai.system_instructions, i messaggi della richiesta in gen_ai.input.messages e la risposta in gen_ai.output.messages.

Per ogni span e i relativi attributi, consulta il riferimento degli span OpenTelemetry.

Una sessione di Managed Agents

Una sessione ha uno span per ogni richiesta alla Sessions API e uno span di turno per ogni turno dell'agente. Un turno avviato da una richiesta è figlio dello span di quella richiesta. Un turno contiene uno span per ogni richiesta al modello e per ogni strumento eseguito dall'API, tranne nei casi elencati nel riferimento sugli span degli strumenti. Contiene inoltre uno span per ogni valutazione dell'esito.

Questo esempio segue una richiesta di chat, in cui la tua applicazione invia un messaggio a una sessione ed esegue uno strumento personalizzato. La traccia contiene span sia della tua applicazione sia dell'API, nel seguente ordine:

1. La tua applicazione riceve una richiesta POST /chat da un utente.
2. La tua applicazione avvia il session tool runner dell'SDK, che elenca e trasmette in streaming gli eventi della sessione (mostrati come gli span anthropic.sessions.events.stream e anthropic.sessions.events.list).
3. La tua applicazione invia il messaggio dell'utente alla sessione chiamando sessions.events.send.
4. Inizia un turno che include richieste al modello, un uso dello strumento bash e un turno su un altro thread (mostrati come il primo span anthropic.session.turn e gli span sotto di esso).
5. Il modello chiede di usare lo strumento personalizzato list_issues, quindi il turno termina con il motivo di arresto requires_action.
6. Il session tool runner esegue list_issues (mostrato come lo span anthropic.custom_tool_use list_issues) e invia il suo risultato chiamando sessions.events.send.
7. Inizia un secondo turno con il risultato dello strumento (mostrato come l'ultimo span anthropic.session.turn).

L'SDK nella tua applicazione emette lo span anthropic.custom_tool_use e lo span client di ogni richiesta. Per ottenere questi span, configura il tracciamento dell'SDK.

Gli span di una sessione possono trovarsi in più tracce, ad esempio quando invii una richiesta successiva da una nuova traccia radice. Con il multiagente attivo, una sessione può anche avere più thread. Per trovare gli span di cui hai bisogno, raggruppali per un ID.

• Un thread: Raggruppa gli span per gen_ai.conversation.id, che contiene l'ID del thread della sessione. Ordinali per ora di inizio per leggere il thread come una trascrizione.
• Un'intera sessione, con tutti i suoi thread: Raggruppa gli span per anthropic.session.id, attraverso le tracce.

Con Contenuto completo, puoi leggere il contenuto di una sessione dai suoi span.

• Per leggere il contenuto di un turno, usa il suo span di turno. Il prompt di sistema si trova in gen_ai.system_instructions sul primo span di turno di un thread, l'input in gen_ai.input.messages (i tuoi messaggi e i risultati degli strumenti, gli eventi system.message e i messaggi da altri thread) e l'output in gen_ai.output.messages (i messaggi dell'agente, gli usi degli strumenti e i risultati degli strumenti).
• Per vedere gli argomenti e il risultato di un uso di uno strumento, leggi il suo span dello strumento. Gli argomenti si trovano in gen_ai.tool.call.arguments e il risultato in anthropic.tool_result.content.

Per ogni span e i suoi attributi, consulta il riferimento sugli span OpenTelemetry.

Conteggio dei token

Per contare ogni token una sola volta, somma gli span di una sola fonte per ogni richiesta. Quando una richiesta alla Messages API ha sia uno span dell'SDK sia uno span dell'API, somma i suoi span dell'API. Entrambi si chiamano anthropic.messages.create, quindi distinguili in base al tipo: lo span dell'SDK è CLIENT e il suo figlio, lo span dell'API, è SERVER.

Per ogni fonte, somma solo i seguenti span, perché alcuni attributi di utilizzo si ripetono su più di un livello degli span dell'API:

• Span dell'SDK: Somma gli span anthropic.messages.create. Se una richiesta ha delle compattazioni, aggiungi anche anthropic.usage.compaction.input_tokens e anthropic.usage.compaction.output_tokens dello span, perché gli attributi gen_ai.usage.* non includono i token di compattazione. Se un modello di fallback ha servito una richiesta, il suo span contiene l'utilizzo solo del modello che ha servito la risposta.
• Span dell'API di una richiesta alla Messages API: Somma gli span anthropic.messages.create oppure i loro span anthropic.model_request, non entrambi. Se una richiesta ha delle compattazioni, aggiungi anche i suoi span anthropic.compaction. Non aggiungere anche gli attributi anthropic.usage.compaction.* dello span anthropic.messages.create, perché contengono gli stessi token.
• Span dell'API di una sessione di Managed Agents: Somma gli span anthropic.model_request e anthropic.session.outcome_evaluation.

Gli span possono arrivare più di una volta, ad esempio quando una consegna viene ritentata. Se la tua piattaforma di osservabilità non rimuove i duplicati, conta ogni span una sola volta in base al suo ID di traccia e ID di span.

gen_ai.usage.input_tokens include già i token letti dalla e scritti nella cache dei prompt, quindi non aggiungervi gli attributi della cache. Per tutti gli attributi di utilizzo, consulta Utilizzo dei token.