Sie können vollständige Audit-Telemetrie von Office-Agenten an Ihren eigenen OpenTelemetry (OTEL)-Collector weiterleiten. Dies gibt Ihrer Organisation vollständige Kontrolle über Aufbewahrung, Verschlüsselung und Integration mit Ihrer SIEM- oder Observability-Plattform.
Diese Anleitung behandelt die Aktivierung eines benutzerdefinierten Collectors, welche Daten Sie erhalten, und die vollständige Span-Schema-Referenz.
Benutzerdefinierte OTEL-Collector sind für Claude Enterprise-Organisationen und für Direct-Provider-Bereitstellungen (Amazon Bedrock, Google Vertex AI oder ein Gateway) verfügbar.
Was Sie erhalten
Wenn Sie einen benutzerdefinierten Collector konfigurieren, senden Office-Agenten Trace-Daten für jeden Benutzer-Turn. Jeder Turn erzeugt einen Baum von Spans, die den Prompt, Modellaufrufe, Tool-Ausführungen, Datei-Uploads und Context-Komprimierungsereignisse erfassen.
Ihr Collector empfängt alle Span-Attribute, einschließlich derjenigen, die benutzergenerierte Inhalte enthalten (Prompt-Text, Tool-Eingaben und -Ausgaben, Dokument-URLs und Dateinamen). Keine Attribute werden redaktioniert oder gefiltert. Der Antworttext des Assistenten ist nicht in den emittierten Span-Daten enthalten. Ihre Organisation besitzt diese Daten.
Wichtig: Metriken werden nicht an benutzerdefinierte Collector gesendet. Der office_agent.* Counter-Namespace wird nur an Anthropic weitergeleitet. Jedoch erscheint jede Counter-Erhöhung auch als Span-Ereignis auf dem aktiven Span, sodass die gleichen Signale in Ihren Traces verfügbar sind.
Telemetrie wird über OTLP/HTTP an Ihren Endpunkt unter {your_url}/v1/traces gesendet. gRPC wird nicht unterstützt, da das Add-in in einer Office WebView ausgeführt wird.
Aktivieren Sie einen benutzerdefinierten Collector
Das Setup unterscheidet sich je nachdem, wie sich Ihre Organisation bei Claude authentifiziert.
Wichtig: Wenn ein benutzerdefinierter Endpunkt konfiguriert ist, wird die Telemetrie ausschließlich an Ihren Collector gesendet. Spans werden nicht doppelt an Anthropic gesendet.
Claude Enterprise (OAuth)-Organisationen
Ein Organisationsadministrator legt den Collector-Endpunkt in der Claude.ai-Administrationskonsole unter Organisationseinstellungen > Office-Agenten fest. Die Einstellung gilt organisationsweit.
Einstellung | Beschreibung |
| Basis-URL Ihres OTLP-Collectors. Das Add-in fügt /v1/traces an. HTTPS wird dringend empfohlen. |
| Optionale Authentifizierungsheader, formatiert gemäß der OpenTelemetry-Spezifikation: key1=value1,key2=value2 |
Das Protokoll muss HTTP-basiertes OTLP sein. gRPC wird zum Zeitpunkt der Konfiguration abgelehnt.
Direct-Provider-Bereitstellungen (Amazon Bedrock, Google Vertex AI, Gateway)
Bei Bereitstellungen, die sich gegen Ihren eigenen Modell-Provider authentifizieren, anstatt gegen Claude.ai, wird der Collector-Endpunkt über einen von drei Konfigurationskanälen bereitgestellt. Alle drei verwenden die gleichen zwei Schlüssel.
Empfohlen: Verwenden Sie das claude-in-office Plugin für Claude Code. Es führt Sie durch die Generierung des Manifests, die Registrierung von Entra-Erweiterungsattributen und die Einrichtung eines Bootstrap-Endpunkts mit vorkonfiguriertem otlp_endpoint und otlp_headers. Die drei unten dokumentierten Kanäle dienen als Referenz und für manuelle Einrichtung.
Schlüssel | Format | Beschreibung |
| HTTPS-URL | Basis-URL Ihres OTLP-Collectors. Das Add-in entfernt alle nachfolgenden Schrägstriche und fügt /v1/traces an. |
| key1=value1,key2=value2 | Optionale Authentifizierungsheader. Gleiches Format wie die OpenTelemetry-Umgebungsvariable OTEL_EXPORTER_OTLP_HEADERS. |
Wenn otlp_endpoint nicht gesetzt oder leer ist, wird kein benutzerdefinierter Collector konfiguriert und das Add-in fällt auf das Standardverhalten zurück.
Hinweis: Diese Konfigurationskanäle gelten nur für Microsoft Office-Bereitstellungen. Google Workspace Add-ins werden separat konfiguriert.
Kanal 1: Manifest-URL-Parameter
Fügen Sie die Schlüssel als Query-String-Parameter zur Taskpane-URL in Ihrem benutzerdefinierten Add-in-Manifest hinzu:
URL-kodieren Sie die Werte. Dies wendet die Konfiguration auf jeden Benutzer an, der das Manifest installiert.
Kanal 2: Azure Entra ID-Verzeichniserweiterung
Für benutzerspezifische Konfiguration registrieren Sie die Schlüssel als Entra ID-Verzeichniserweiterungsattribute und weisen Sie sie über Microsoft Graph zu. Das Add-in liest sie aus dem ID-Token des Benutzers mithilfe von Nested App Authentication (NAA).
Die Anspruchsnamen im ausgegebenen ID-Token folgen dem Azure-Verzeichniserweiterungsformat:
Anspruch | Zuordnung zu |
| otlp_endpoint |
| otlp_headers |
Legen Sie diese pro Benutzer mit einem Graph PATCH gegen das Benutzerobjekt fest. Azure kodiert Verzeichniserweiterungswerte als Single-Element-Arrays im ID-Token; das Add-in entpackt sie automatisch. Dieser Kanal erfordert entra_sso=1 in den Manifest-URL-Parametern, um die NAA-Token-Akquisition zu aktivieren.
Kanal 3: Bootstrap-Endpunkt-Antwort
Wenn Ihre Bereitstellung einen Bootstrap-Endpunkt verwendet (einen JSON-Endpunkt, den Ihre Organisation hostet und den das Add-In beim Start aufruft), fügen Sie die Schlüssel in den Antwortkörper ein:
{
"otlp_endpoint": "https://otel-collector.your-domain.com",
"otlp_headers": "Authorization=Bearer <token>"
}Die Bootstrap-Endpunkt-URL selbst wird über bootstrap_url in den Manifest-URL-Parametern oder einem Entra-extn.bootstrap_url-Anspruch konfiguriert. Wenn ein Entra-ID-Token erworben wurde, wird es als Bearer-Autorisierungsheader an den Bootstrap-Endpunkt übergeben, damit Ihr Endpunkt den Benutzer authentifizieren kann, bevor er benutzerspezifische Konfiguration zurückgibt.
Priorität
Wenn mehrere Kanäle einen Wert bereitstellen, überschreiben spätere Kanäle frühere: Manifest-Parameter werden zuerst gelesen, dann Entra-Ansprüche, dann die Bootstrap-Antwort. Die Bootstrap-Antwort hat Vorrang.
Falls noch nicht geschehen, ist der schnellste Weg das claude-in-office-Plugin.
Bereitstellungsmodi
Der benutzerdefinierte Collector-Export ist in beiden Bereitstellungsmodi verfügbar:
Claude.ai Enterprise (OAuth): vollständige Audit-Spur einschließlich Benutzeridentität (
user.email,user.account_uuid,organization.id), MCP-Server-Metadaten und Datei-Upload-Datensätze.Direkter Anbieter (Bedrock, Vertex AI, Gateway): Kern-Audit-Spur (Prompts, Tool-Eingaben und -Ausgaben, Dokument-URLs), aber keine Benutzeridentität, keine MCP-Metadaten und keine Datei-Upload-Spans. Die Benutzer-Attribution erfordert die Korrelation von
session.idmit Ihren eigenen Identity-Provider-Protokollen.
Die Kern-Audit-Nutzlast ist in beiden Modi identisch. Direktanbieter-Bereitstellungen verfügen nicht über Claude.ai-Kontokontext, daher fehlen Attribute, die vom Claude.ai-Benutzer- oder Organisationsprofil abgeleitet sind. Siehe die [claude.ai-only]-Tags im Span-Schema unten für die vollständige Liste.
Oberflächen- und Anbieter-Labels
Jeder Span enthält zwei Labels, die identifizieren, welche Office-Anwendung und Plattform ihn generiert haben. Verwenden Sie diese als Ihre primären Dimensionen zum Filtern und für Dashboards.
Label | Werte |
| sheet (Excel), doc (Word), slide (PowerPoint), mail (Outlook) |
| m (Microsoft) |
Span-Referenz
Jede Benutzer-Eingabe erzeugt einen Eltern-/Kind-Baum von bis zu fünf Span-Typen. Attribute, die mit [content] gekennzeichnet sind, enthalten benutzergenerierte Daten; diese bilden Ihre Audit-Nutzlast. Attribute, die mit [claude.ai-only] gekennzeichnet sind, werden nur ausgefüllt, wenn sich der Benutzer mit einem Claude-Konto anmeldet; sie fehlen bei Bedrock-, Vertex-AI- und Gateway-Bereitstellungen. Fehlende Attribute werden vollständig aus dem Span weggelassen (kein Schlüssel mit Nullwert).
Der file.upload-Span und alle mcp.*-Attribute sind ebenfalls [claude.ai-only], da Datei-Upload und MCP-Server-Verbindungen Claude-Plattform-Features sind.
Bei direkten Anbieter-Bereitstellungen sollte die Benutzeridentität über session.id und document.url korreliert werden, verbunden mit den Sitzungsprotokollen Ihres Identity Providers.
Ressourcen-Attribute
Diese Attribute erscheinen auf jedem Span:
Attribut | Beschreibung |
| Fester Wert: office-agent |
| Fester Wert: 1.0.0 |
| Build-Commit-Identifier |
agent.query (Root-Span)
Ein Span pro Benutzer-Eingabe. Dies ist die Wurzel des Span-Baums und enthält Sitzungsidentität, Dokumentkontext und MCP-Server-Status. SpanKind: INTERNAL.
Attribut | Beschreibung |
| sheet | doc | slide | mail |
| m |
| Die Eingabeaufforderung des Benutzers (erste 4000 Zeichen) |
| Undurchsichtiger Sitzungsidentifier |
| E-Mail-Adresse des Benutzers |
| Deterministischer Hash-Bucket (SHA-256 der E-Mail, mod 30) |
| Claude-Konto-UUID |
| URL des offenen Office-Dokuments |
| Claude-Organisations-UUID |
| Claude-Abonnement-Tier |
| Claude-Organisationstyp |
| Vom Benutzer für diese Sitzung ausgewähltes Modell |
| PC | Mac | OfficeOnline | iOS | Android | Universal |
| Office-Build-Nummer |
| Anzahl der konfigurierten MCP-Server |
| Anzahl der erfolgreich verbundenen MCP-Server |
| Anzahl der MCP-Server, die nicht verbunden werden konnten |
| success | error | timeout | no_auth | not_attempted |
| Dauer des MCP-Registry-Abrufs |
| HTTP-Statuscode des MCP-Registry-Abrufs |
| Serialisierte MCP-Serverdetails (Namen, Toolanzahl, Fehlermeldungen) |
| Anzahl der an diesen Zug angehängten Dateien |
| Insgesamt hochgeladene Bytes |
| Anzahl der Bildanhänge |
| Anzahl der Dokumentanhänge |
| Anzahl der sonstigen Anhänge |
| Ausnahmeklassenname (bei Fehler vorhanden) |
| Phase, in der die Abfrage fehlgeschlagen ist (bei Fehler vorhanden) |
agent.stream
Ein Span pro API-Aufruf an Claude als untergeordneter Span des Abfrage-Spans. SpanKind: CLIENT.
Attribut | Beschreibung |
| Modell-ID für diesen Aufruf |
| Maximal angeforderte Ausgabe-Token |
| Anzahl der Nachrichten in der Konversation beim Start des Streams |
| Eingabe-Token abgerechnet (aus API-Antwort) |
| Ausgabe-Token abgerechnet (aus API-Antwort) |
| Token aus Prompt-Cache bereitgestellt |
| Token in Prompt-Cache geschrieben |
| end_turn | tool_use | max_tokens | usw. |
| Anthropic-API-Header request-id, verwendbar für Support-Korrelation |
Hinweis zum Prompt-Caching: Das Add-in fordert Prompt-Caching bedingungslos an. Die Attribute cache_read_tokens und cache_creation_tokens werden aus der API-Antwort des Anbieters gesetzt und werden weggelassen, wenn die Antwort sie nicht enthält. Prompt-Caching ist auf der Claude-Plattform verfügbar; zum Zeitpunkt dieser Veröffentlichung geben Amazon Bedrock und Google Vertex AI diese Felder über den vom Add-in verwendeten Client noch nicht zurück. Wenn die Unterstützung bei Ihrem Anbieter verfügbar wird, werden diese Attribute automatisch angezeigt.
agent.tool_execution
Ein Span pro Tool-Aufruf als untergeordnetes Element des Stream-Spans. SpanKind: INTERNAL. Dies ist der primäre Datensatz der Aktionen, die das Modell gegen das Dokument ausgeführt hat.
Attribut | Beschreibung |
| Tool-Bezeichner (z. B. get_cell_ranges, execute_office_js, edit_slide_xml) |
| Eindeutige ID dieses Tool-Aufrufs |
| server | client |
| first_party | mcp | server |
| read | write | read_write |
| manual | auto_accept | deferred |
| Serialisierte Tool-Eingabe (erste 4000 Zeichen) |
| Boolesch |
| Serialisierte Tool-Ausgabe (erste 4000 Zeichen) |
| Vollständige Ausgabelänge in Zeichen (zur Erkennung von Kürzungen verwenden) |
| Fehlerklassifizierung (bei Fehler vorhanden) |
| Gelesene Zellen (nur Blattoberfläche) |
| Geschriebene Zellen (nur Blattoberfläche) |
| Kopierte Zellen (nur Blattoberfläche) |
Hinweis: Das Attribut tool.accept_decision dokumentiert, wie die Genehmigungsentscheidung getroffen wurde: manual (der Benutzer hat diese spezifische Aktion genehmigt), auto_accept (der Benutzer hatte zuvor eine dauerhafte Genehmigung erteilt), oder deferred (die Aktion wurde zur späteren Überprüfung in die Warteschlange eingereiht). Verwenden Sie dies, um Genehmigungsmuster in Ihrer Organisation zu überprüfen.
agent.compaction
Eine Spanne pro Konversation mit automatischer Zusammenfassung, ausgelöst wenn der Kontext sich dem Fenster-Limit nähert. SpanKind: CLIENT.
Attribut | Beschreibung |
| Token-Anzahl vor der Zusammenfassung |
| Token-Anzahl nach der Zusammenfassung |
| Delta |
| Boolesch |
| Derzeit immer reaktiv |
Diese Spanne enthält auch agent.surface, agent.vendor, session.id, user.email [claude.ai-only], user.bucket [claude.ai-only], office.platform und office.version, dupliziert aus der Root-Spanne, damit Sie Komprimierungsereignisse unabhängig abfragen können.
file.upload [claude.ai-only]
Eine Spanne pro einzelnem Datei-Upload als untergeordnete Spanne der Abfrage-Spanne. SpanKind: CLIENT. Dieser Spanntyp wird nur angezeigt, wenn sich Benutzer mit einem Claude.ai-Konto anmelden. Datei-Upload ist bei direkten Provider-Bereitstellungen nicht verfügbar.
Attribut | Beschreibung |
| Ursprünglicher Dateiname |
| Dateigröße |
| MIME-Typ |
| Anthropic Files API-Bezeichner |
| Boolesch |
Spannenereignisse
Spannenereignisse sind Zeitstempel-Marker, die an die obigen Spannen angehängt sind. Sie erfassen Lebenszyklusübergänge und äquivalente Zählersignale.
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}
Jeder interne Produktzähler zeichnet auch ein Spannenereignis mit demselben Namen auf der aktuell aktiven Spanne auf und bietet das Äquivalent des Metrik-Streams in Ihren Trace-Daten. Das Ereignis office_agent.token.usage wird auf jeder agent.stream-Spanne einmal pro Nicht-Null-Token-Typ mit Attributen {token_usage.type: input | output | cacheRead | cacheCreation, token_usage.model, token_usage.token_count} ausgegeben. Dies spiegelt die Form des *.token.usage-Zählers wider, der von anderen Anthropic-Produkten ausgegeben wird, sodass ein einzelner Collector Token-Kosten produktübergreifend aggregieren kann, indem er nach service.name gruppiert.
Oberflächenspezifisches Verhalten
Das Telemetrie-Schema ist über alle Oberflächen hinweg konsistent. Dies sind die Unterschiede:
Sheets (Excel):
agent.tool_execution-Spannen enthalten die Attributesheet.cells_read,sheet.cells_writtenundsheet.cells_copied.office_agent.cell_edit_collision_total-Spannenereignisse werden angezeigt, wenn ein Benutzer sich mitten in einer Zellenbearbeitung befindet, während ein Tool versucht zu schreiben.Documents (Word): Dokumentbearbeitungs-Trichter-Ereignisse verfolgen den Bearbeitungslebenszyklus:
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. Keinesheet.cells_*-Attribute.Slides (PowerPoint): keine oberflächenspezifischen Attribute oder Ereignisse über das gemeinsame Schema hinaus.
Mail (Outlook): keine oberflächenspezifischen Attribute oder Ereignisse über das gemeinsame Schema hinaus.
Rekonstruktion einer Benutzersitzung
Claude.ai-Bereitstellungen
Filtern Sie Spannen nach
user.email(oderuser.account_uuid) undsession.id.Ordnen Sie
agent.query-Spannen nach Start-Zeitstempel; jede ist eine Benutzereingabe.Für jeden Durchgang ist
user.messagedie Eingabeaufforderung unddocument.urlist die bearbeitete Datei.Untergeordnete
agent.tool_execution-Spannen, nach Zeitstempel geordnet, sind die durchgeführten Aktionen:tool.inputist das Versuchte,tool.outputist das Ergebnis,tool.accept_decisionzeichnet auf, ob der Benutzer explizit genehmigt hat.
Direkte Provider-Bereitstellungen
Das Add-In hat in diesem Modus keine Claude.ai-Benutzeridentität, daher enthalten Spannen keine user.email oder user.account_uuid. Um Aktivitäten einem Benutzer zuzuordnen:
Filtern Sie Spans nach
session.id, um eine kontinuierliche Add-In-Sitzung zu isolieren.Verwenden Sie
document.url, um die bearbeitete Datei zu identifizieren.Korrelieren Sie die Sitzung mit den Protokollen Ihres Identitätsanbieters: Entra-Anmeldeereignisse, Gateway-Zugriffsprotokolle oder das Anforderungsprotokoll Ihres Bootstrap-Endpunkts (das das Entra-ID-Token des Benutzers als Bearer-Header empfängt).
Sobald eine Sitzung einem Benutzer zugeordnet ist, ist die Rekonstruktion pro Durchgang identisch: agent.query-Spans, geordnet nach Zeitstempel, mit
user.message,tool.input,tool.outputundtool.accept_decision, die die Audit-Spur bereitstellen.
Dies erzeugt ein vollständiges, geordnetes Transkript der Interaktion in beiden Bereitstellungsmodi.