Puoi instradare la telemetria di audit completa dagli agenti Office al tuo collector OpenTelemetry (OTEL) personalizzato. Questo dà alla tua organizzazione il controllo completo sulla conservazione, la crittografia e l'integrazione con il tuo SIEM o la piattaforma di osservabilità.
Questa guida spiega come abilitare un collector personalizzato, quali dati riceverai e il riferimento completo dello schema span.
I collector OTEL personalizzati sono disponibili per le organizzazioni Claude Enterprise e per le distribuzioni direct-provider (Amazon Bedrock, Google Vertex AI o un gateway).
Cosa riceverai
Quando configuri un collector personalizzato, gli agenti Office inviano dati di traccia che coprono ogni turno utente. Ogni turno produce un albero di span che cattura il prompt, le chiamate al modello, le esecuzioni di strumenti, i caricamenti di file e gli eventi di compattazione del contesto.
Il tuo collector riceve tutti gli attributi span, inclusi quelli che contengono contenuti generati dall'utente (testo del prompt, input e output degli strumenti, URL dei documenti e nomi di file). Nessun attributo viene redatto o filtrato. Il testo della risposta dell'assistente non è incluso nei dati span emessi. La tua organizzazione possiede questi dati.
Importante: Le metriche non vengono inviate ai collector personalizzati. Lo spazio dei nomi del contatore office_agent.* viene instradato solo ad Anthropic. Tuttavia, ogni incremento del contatore appare anche come evento span sullo span attivo, quindi gli stessi segnali sono disponibili nelle tue tracce.
La telemetria viene inviata tramite OTLP/HTTP al tuo endpoint in {your_url}/v1/traces. gRPC non è supportato perché il componente aggiuntivo viene eseguito in una WebView di Office.
Abilitare un collector personalizzato
La configurazione varia a seconda di come la tua organizzazione si autentica con Claude.
Importante: Quando è configurato un endpoint personalizzato, la telemetria va esclusivamente al tuo collector. Gli span non vengono inviati in duplicato ad Anthropic.
Organizzazioni Claude Enterprise (OAuth)
Un amministratore dell'organizzazione imposta l'endpoint del collector nella console di amministrazione Claude.ai in Impostazioni organizzazione > Agenti Office. L'impostazione si applica a livello di organizzazione.
Impostazione | Descrizione |
| URL di base del tuo collector OTLP. Il componente aggiuntivo aggiunge /v1/traces. HTTPS fortemente consigliato. |
| Intestazioni di autenticazione opzionali, formattate secondo la specifica OpenTelemetry: key1=value1,key2=value2 |
Il protocollo deve essere OTLP basato su HTTP. gRPC viene rifiutato al momento della configurazione.
Distribuzioni direct-provider (Amazon Bedrock, Google Vertex AI, gateway)
Per le distribuzioni che si autenticano rispetto al tuo provider di modelli anziché a Claude.ai, l'endpoint del collector viene fornito tramite uno di tre canali di configurazione. Tutti e tre utilizzano le stesse due chiavi.
Consigliato: Utilizza il plugin claude-in-office per Claude Code. Ti guida nella generazione del manifest, nella registrazione degli attributi di estensione Entra e nella configurazione di un endpoint bootstrap con otlp_endpoint e otlp_headers preconfigurati. I tre canali di seguito sono documentati come riferimento e per la configurazione manuale.
Chiave | Formato | Descrizione |
| URL HTTPS | URL di base del tuo collector OTLP. Il componente aggiuntivo rimuove qualsiasi barra finale e aggiunge /v1/traces. |
| key1=value1,key2=value2 | Intestazioni di autenticazione opzionali. Stesso formato della variabile di ambiente OTEL_EXPORTER_OTLP_HEADERS di OpenTelemetry. |
Se otlp_endpoint non è impostato o è vuoto, nessun collector personalizzato è configurato e il componente aggiuntivo ritorna al comportamento predefinito.
Nota: Questi canali di configurazione si applicano solo alle distribuzioni di Microsoft Office. I componenti aggiuntivi di Google Workspace sono configurati separatamente.
Canale 1: Parametro URL del manifest
Aggiungi le chiavi come parametri della stringa di query all'URL del riquadro attività nel tuo manifest del componente aggiuntivo personalizzato:
Codifica URL i valori. Questo applica la configurazione a ogni utente che installa il manifest.
Canale 2: Estensione della directory Azure Entra ID
Per la configurazione per utente, registra le chiavi come attributi di estensione della directory Entra ID e assegnale tramite Microsoft Graph. Il componente aggiuntivo le legge dal token ID dell'utente utilizzando l'autenticazione app nidificata (NAA).
I nomi delle attestazioni nel token ID emesso seguono il formato di estensione della directory di Azure:
Attestazione | Mappa a |
| otlp_endpoint |
| otlp_headers |
Imposta questi per utente con un PATCH di Graph rispetto all'oggetto utente. Azure codifica i valori di estensione della directory come array a elemento singolo nel token ID; il componente aggiuntivo li estrae automaticamente. Questo canale richiede entra_sso=1 nei parametri dell'URL del manifest per abilitare l'acquisizione del token NAA.
Canale 3: Risposta dell'endpoint di bootstrap
Se la tua distribuzione utilizza un endpoint di bootstrap (un endpoint JSON ospitato dalla tua organizzazione che il componente aggiuntivo chiama all'avvio), includi le chiavi nel corpo della risposta:
{
"otlp_endpoint": "https://otel-collector.your-domain.com",
"otlp_headers": "Authorization=Bearer <token>"
}L'URL dell'endpoint di bootstrap stesso è configurato tramite bootstrap_url nei parametri dell'URL del manifesto o in un'attestazione Entra extn.bootstrap_url. Se è stato acquisito un token ID Entra, viene passato all'endpoint di bootstrap come intestazione di autorizzazione Bearer, in modo che il tuo endpoint possa autenticare l'utente prima di restituire la configurazione per utente.
Precedenza
Quando più canali forniscono un valore, i canali successivi sovrascrivono quelli precedenti: i parametri del manifesto vengono letti per primi, poi le attestazioni Entra, quindi la risposta di bootstrap. La risposta di bootstrap ha la priorità.
Se non l'hai già fatto, il percorso più veloce è il plugin claude-in-office.
Modalità di distribuzione
L'esportazione del raccoglitore personalizzato è disponibile in entrambe le modalità di distribuzione:
Claude.ai Enterprise (OAuth): traccia di controllo completa inclusa l'identità dell'utente (
user.email,user.account_uuid,organization.id), metadati del server MCP e record di caricamento file.Provider diretto (Bedrock, Vertex AI, gateway): traccia di controllo principale (prompt, input e output degli strumenti, URL dei documenti) ma senza identità dell'utente, senza metadati MCP e senza intervalli di caricamento file. L'attribuzione dell'utente richiede la correlazione di
session.idrispetto ai log del tuo provider di identità.
Il payload di controllo principale è identico in entrambe le modalità. Le distribuzioni del provider diretto mancano del contesto dell'account Claude.ai, quindi gli attributi derivati dal profilo utente o organizzazione Claude.ai sono assenti. Consulta i tag [claude.ai-only] nello schema di intervallo sottostante per l'elenco completo.
Etichette di superficie e fornitore
Ogni intervallo include due etichette che identificano quale applicazione Office e quale piattaforma lo hanno generato. Utilizzale come dimensioni principali per il filtraggio e i dashboard.
Etichetta | Valori |
| sheet (Excel/Google Sheets), doc (Word), slide (PowerPoint) |
| m (Microsoft) |
Riferimento intervallo
Ogni turno dell'utente produce un albero padre/figlio di fino a cinque tipi di intervallo. Gli attributi contrassegnati [content] contengono dati generati dall'utente; questi formano il tuo payload di controllo. Gli attributi contrassegnati [claude.ai-only] vengono popolati solo quando l'utente accede con un account Claude; sono assenti nelle distribuzioni Bedrock, Vertex AI e gateway. Gli attributi assenti vengono omessi dall'intervallo interamente (nessuna chiave con valore null).
L'intervallo file.upload e tutti gli attributi mcp.* sono anche [claude.ai-only], poiché il caricamento di file e le connessioni del server MCP sono funzionalità della piattaforma Claude.
Per le distribuzioni del provider diretto, l'identità dell'utente deve essere correlata tramite session.id e document.url, uniti ai log della sessione del tuo provider di identità.
Attributi di risorsa
Questi attributi appaiono su ogni intervallo:
Attributo | Descrizione |
| Valore fisso: office-agent |
| Valore fisso: 1.0.0 |
| Identificatore del commit di compilazione |
agent.query (intervallo radice)
Un intervallo per turno dell'utente. Questo è il root dell'albero degli intervalli e contiene l'identità della sessione, il contesto del documento e lo stato del server MCP. SpanKind: INTERNAL.
Attributo | Descrizione |
| sheet | doc | slide |
| m |
| Il prompt dell'utente (primi 4000 caratteri) |
| Identificatore di sessione opaco |
| Indirizzo email dell'utente |
| Bucket hash deterministico (SHA-256 dell'email, mod 30) |
| UUID account Claude |
| URL del documento Office aperto |
| UUID organizzazione Claude |
| Livello di abbonamento Claude |
| Tipo di organizzazione Claude |
| Modello selezionato dall'utente per questa sessione |
| PC | Mac | OfficeOnline | iOS | Android | Universal |
| Numero di build di Office |
| Numero di server MCP configurati |
| Numero di server MCP connessi con successo |
| Numero di server MCP che non si sono connessi |
| success | error | timeout | no_auth | not_attempted |
| Durata del recupero del registro MCP |
| Codice di stato HTTP del recupero del registro MCP |
| Dettagli del server MCP serializzati (nomi, conteggi degli strumenti, messaggi di errore) |
| Numero di file allegati a questo turno |
| Byte totali caricati |
| Numero di allegati immagine |
| Numero di allegati documento |
| Numero di altri allegati |
| Nome della classe di eccezione (presente in caso di errore) |
| Fase in cui la query non è riuscita (presente in caso di errore) |
agent.stream
Un span per ogni chiamata API a Claude, come figlio dello span della query. SpanKind: CLIENT.
Attributo | Descrizione |
| ID del modello utilizzato per questa chiamata |
| Token di output massimi richiesti |
| Numero di messaggi nella conversazione all'inizio dello stream |
| Token di input fatturati (dalla risposta API) |
| Token di output fatturati (dalla risposta API) |
| Token serviti dalla cache del prompt |
| Token scritti nella cache del prompt |
| end_turn | tool_use | max_tokens | ecc. |
| Header request-id dell'API Anthropic, utilizzabile per la correlazione del supporto |
Nota sulla cache del prompt: Il componente aggiuntivo richiede la cache del prompt in modo incondizionato. Gli attributi cache_read_tokens e cache_creation_tokens sono impostati dalla risposta API del provider e vengono omessi quando la risposta non li include. La cache del prompt è disponibile per la piattaforma Claude Developer; al momento della stesura, Amazon Bedrock e Google Vertex AI non restituiscono ancora questi campi tramite il client utilizzato dal componente aggiuntivo. Quando il supporto arriverà sul tuo provider, questi attributi inizieranno a comparire automaticamente.
agent.tool_execution
Uno span per ogni chiamata di strumento, come figlio dello span di stream. SpanKind: INTERNAL. Questo è il record principale delle azioni intraprese dal modello sul documento.
Attributo | Descrizione |
| Identificatore dello strumento (ad es. get_cell_ranges, execute_office_js, edit_slide_xml) |
| ID univoco di questa invocazione dello strumento |
| server | client |
| first_party | mcp | server |
| read | write | read_write |
| manual | auto_accept | deferred |
| Input dello strumento serializzato (primi 4000 caratteri) |
| Booleano |
| Output dello strumento serializzato (primi 4000 caratteri) |
| Lunghezza completa dell'output in caratteri (utilizzare per rilevare il troncamento) |
| Classificazione dell'errore (presente in caso di errore) |
| Celle lette (solo superficie del foglio) |
| Celle scritte (solo superficie del foglio) |
| Celle copiate (solo superficie del foglio) |
Nota: L'attributo tool.accept_decision registra come è stata presa la decisione di autorizzazione: manual (l'utente ha approvato questa azione specifica), auto_accept (l'utente aveva precedentemente concesso un'approvazione permanente), o deferred (l'azione è stata messa in coda per una revisione successiva). Utilizzare questo per controllare i modelli di approvazione nell'organizzazione.
agent.compaction
Un span per conversazione con auto-riepilogo, attivato quando il contesto si avvicina al limite della finestra. SpanKind: CLIENT.
Attributo | Descrizione |
| Conteggio token prima del riepilogo |
| Conteggio token dopo il riepilogo |
| Delta |
| Booleano |
| Attualmente sempre reattivo |
Questo span contiene anche agent.surface, agent.vendor, session.id, user.email [claude.ai-only], user.bucket [claude.ai-only], office.platform e office.version, duplicati dallo span radice in modo da poter interrogare gli eventi di compattazione in modo indipendente.
file.upload [claude.ai-only]
Uno span per ogni caricamento di file individuale, come figlio dello span di query. SpanKind: CLIENT. Questo tipo di span appare solo quando gli utenti accedono con un account Claude.ai. Il caricamento di file non è disponibile nelle distribuzioni dirette del provider.
Attributo | Descrizione |
| Nome file originale |
| Dimensione file |
| Tipo MIME |
| Identificatore API Anthropic Files |
| Booleano |
Eventi span
Gli eventi span sono marcatori con timestamp allegati agli span precedenti. Catturano transizioni del ciclo di vita e segnali equivalenti ai contatori.
agent.query: exception {exception.type}; file_upload {file_id, mime_type, content_category}agent.stream: first_token; stream_complete; stream_error {exception.type}agent.tool_execution: tool_init; tool_run; tool_result; tool_error {error_type}agent.compaction: compaction_start; compaction_complete; compaction_error {exception.type}file.upload: exception {exception.type}
Ogni contatore di prodotto interno registra anche un evento span con lo stesso nome sullo span attualmente attivo, fornendo l'equivalente del flusso di metriche all'interno dei dati di traccia. L'evento office_agent.token.usage viene emesso su ogni span agent.stream, una volta per tipo di token non zero, con attributi {token_usage.type: input | output | cacheRead | cacheCreation, token_usage.model, token_usage.token_count}. Questo rispecchia la forma del contatore *.token.usage emesso da altri prodotti Anthropic, quindi un singolo raccoglitore può aggregare il costo dei token tra i prodotti raggruppando su service.name.
Comportamento specifico della superficie
Lo schema di telemetria è coerente su tutte le superfici. Queste sono le differenze:
Fogli (Excel): gli span
agent.tool_executionincludono gli attributisheet.cells_read,sheet.cells_writtenesheet.cells_copied. Gli eventi spanoffice_agent.cell_edit_collision_totalappaiono quando un utente è in fase di modifica di una cella mentre uno strumento tenta di scrivere.Documenti (Word): gli eventi della canalizzazione di modifica del documento tracciano il ciclo di vita della modifica:
office_agent.doc_edit_received_total,office_agent.doc_edit_parsed_total,office_agent.doc_edit_applied_total,office_agent.doc_proposed_edit_reviewed_total. Nessun attributosheet.cells_*.Diapositive (PowerPoint): nessun attributo o evento specifico della superficie oltre lo schema comune.
Ricostruzione di una sessione utente
Distribuzioni Claude.ai
Filtrare gli span per
user.email(ouser.account_uuid) esession.id.Ordinare gli span
agent.queryper timestamp di inizio; ognuno è un turno utente.Per ogni turno,
user.messageè il prompt edocument.urlè il file su cui si sta lavorando.Gli span figlio
agent.tool_execution, ordinati per timestamp, sono le azioni intraprese:tool.inputè ciò che è stato tentato,tool.outputè il risultato,tool.accept_decisionregistra se l'utente ha approvato esplicitamente.
Distribuzioni dirette del provider
Il componente aggiuntivo non ha identità utente Claude.ai in questa modalità, quindi gli span non contengono user.email o user.account_uuid. Per attribuire l'attività a un utente:
Filtrare gli span per
session.idper isolare una sessione continua del componente aggiuntivo.Usa
document.urlper identificare il file su cui stai lavorando.Correla la sessione rispetto ai log del tuo provider di identità: eventi di accesso Entra, log di accesso del gateway o il log delle richieste dell'endpoint di bootstrap (che riceve il token Entra ID dell'utente come intestazione Bearer).
Una volta che una sessione è attribuita a un utente, la ricostruzione per turno è identica: agent.query ordinati per timestamp, con
user.message,tool.input,tool.outputetool.accept_decisionche forniscono la traccia di controllo.
Questo produce una trascrizione completa e ordinata dell'interazione in entrambe le modalità di distribuzione.