Konfigurieren Sie einen benutzerdefinierten OpenTelemetry-Collector für Office-Agenten

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.

Wenn Sie einen benutzerdefinierten Collector konfigurieren, senden Office-Agenten Trace-Daten, die jeden Benutzerzug abdecken. Jeder Zug erzeugt einen Baum von Spans, die den Prompt, Modellaufrufe, Tool-Ausführungen, Datei-Uploads und Kontext-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 redaktionell bearbeitet oder gefiltert. Der Antworttext des Assistenten ist nicht in den emittierten Span-Daten enthalten. Ihre Organisation besitzt diese Daten.

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.

Das Setup unterscheidet sich je nachdem, wie sich Ihre Organisation bei Claude authentifiziert.

Ein Organisationsadministrator legt den Collector-Endpunkt in der Claude.ai-Administrationskonsole unter Organisationseinstellungen > Office-Agenten fest. Die Einstellung gilt organisationsweit.

Das Protokoll muss HTTP-basiertes OTLP sein. gRPC wird zum Zeitpunkt der Konfiguration abgelehnt.

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.

Wenn otlp_endpoint nicht gesetzt oder leer ist, wird kein benutzerdefinierter Collector konfiguriert und das Add-in fällt auf das Standardverhalten zurück.

Kanal 1: Manifest-URL-Parameter

Fügen Sie die Schlüssel als Abfrageparameter an die Taskpane-URL in Ihrem benutzerdefinierten Add-in-Manifest an:

https://<addin-host>/taskpane.html?otlp_endpoint=https://otel-collector.your-domain.com&otlp_headers=Authorization=Bearer%20<token>

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:

Legen Sie diese benutzerspezifisch 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-Erfassung 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:

Die Bootstrap-Endpunkt-URL selbst wird über bootstrap_url entweder in den Manifest-URL-Parametern oder in 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 die 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.

Der benutzerdefinierte Collector-Export ist in beiden Bereitstellungsmodi verfügbar:

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.

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.

Jede Benutzer-Aktion 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.

Diese Attribute erscheinen auf jedem Span:

Ein Span pro Benutzer-Aktion. Dies ist die Wurzel des Span-Baums und enthält Sitzungsidentität, Dokumentkontext und MCP-Server-Status. SpanKind: INTERNAL.

Ein Span pro API-Aufruf an Claude, als untergeordnetes Element des Abfrage-Spans. SpanKind: CLIENT.

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 diese nicht enthält. Prompt-Caching ist für die Claude Developer Platform verfügbar; zum Zeitpunkt dieser Veröffentlichung geben Amazon Bedrock und Google Vertex AI diese Felder noch nicht über den vom Add-in verwendeten Client zurück. Wenn die Unterstützung bei Ihrem Anbieter verfügbar wird, werden diese Attribute automatisch angezeigt.

Ein Span pro Tool-Aufruf als untergeordnetes Element des Stream-Span. SpanKind: INTERNAL. Dies ist der primäre Datensatz der Aktionen, die das Modell gegen das Dokument ausgeführt hat.

Eine Zusammenfassung pro Konversation mit automatischer Zusammenfassung, ausgelöst wenn der Kontext sich dem Fenster-Limit nähert. SpanKind: CLIENT.

Dieser Span 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 vom Root-Span, damit Sie Komprimierungsereignisse unabhängig abfragen können.

Ein Span pro einzelnem Datei-Upload als untergeordneter Span des Query-Spans. SpanKind: CLIENT. Dieser Span-Typ wird nur angezeigt, wenn sich Benutzer mit einem Claude.ai-Konto anmelden. Datei-Upload ist bei direkten Provider-Bereitstellungen nicht verfügbar.

Span-Ereignisse sind Zeitstempel-Marker, die an die obigen Spans angehängt sind. Sie erfassen Lebenszyklusübergänge und äquivalente Zählersignale.

Jeder interne Produktzähler zeichnet auch ein Span-Ereignis mit demselben Namen auf dem aktuell aktiven Span auf und bietet das Äquivalent des Metrik-Streams in Ihren Trace-Daten. Das office_agent.token.usage-Ereignis wird auf jedem agent.stream-Span 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 *.token.usage-Zählerform wider, die von anderen Anthropic-Produkten ausgegeben wird, sodass ein einzelner Collector Token-Kosten über Produkte hinweg aggregieren kann, indem er nach service.name gruppiert.

Das Telemetrie-Schema ist über alle Oberflächen hinweg konsistent. Dies sind die Unterschiede:

Das Add-In hat in diesem Modus keine Claude.ai-Benutzeridentität, daher enthalten Spans keine user.email oder user.account_uuid. Um Aktivität einem Benutzer zuzuordnen:

Dies erzeugt ein vollständiges, geordnetes Transkript der Interaktion in beiden Bereitstellungsmodi.