Vous pouvez acheminer la télémétrie d'audit complète des agents Office vers votre propre collecteur OpenTelemetry (OTEL). Cela donne à votre organisation un contrôle total sur la rétention, le chiffrement et l'intégration avec votre SIEM ou plateforme d'observabilité.
Ce guide explique comment activer un collecteur personnalisé, les données que vous recevrez et la référence complète du schéma de span.
Les collecteurs OTEL personnalisés sont disponibles pour les organisations Claude Enterprise et pour les déploiements directs (Amazon Bedrock, Google Vertex AI ou une passerelle).
Ce que vous recevrez
Lorsque vous configurez un collecteur personnalisé, les agents Office envoient des données de trace couvrant chaque tour utilisateur. Chaque tour produit un arbre de spans capturant l'invite, les appels de modèle, les exécutions d'outils, les téléchargements de fichiers et les événements de compaction de contexte.
Votre collecteur reçoit tous les attributs de span, y compris ceux contenant du contenu généré par l'utilisateur (texte d'invite, entrées et sorties d'outils, URL de documents et noms de fichiers). Aucun attribut n'est masqué ou filtré. Le texte de réponse de l'assistant n'est pas inclus dans les données de span émises. Votre organisation possède ces données.
Important : Les métriques ne sont pas envoyées aux collecteurs personnalisés. L'espace de noms du compteur office_agent.* est acheminé vers Anthropic uniquement. Cependant, chaque incrément de compteur apparaît également comme un événement de span sur le span actif, de sorte que les mêmes signaux sont disponibles dans vos traces.
La télémétrie est envoyée via OTLP/HTTP à votre point de terminaison à {your_url}/v1/traces. gRPC n'est pas pris en charge car le complément s'exécute dans une WebView Office.
Activer un collecteur personnalisé
La configuration varie selon la façon dont votre organisation s'authentifie auprès de Claude.
Important : Lorsqu'un point de terminaison personnalisé est configuré, la télémétrie est envoyée exclusivement à votre collecteur. Les spans ne sont pas envoyés en double à Anthropic.
Organisations Claude Enterprise (OAuth)
Un administrateur d'organisation définit le point de terminaison du collecteur dans la console d'administration Claude.ai sous Paramètres de l'organisation > Agents Office. Le paramètre s'applique à l'ensemble de l'organisation.
Paramètre | Description |
| URL de base de votre collecteur OTLP. Le complément ajoute /v1/traces. HTTPS fortement recommandé. |
| En-têtes d'authentification optionnels, formatés selon la spécification OpenTelemetry : clé1=valeur1,clé2=valeur2 |
Le protocole doit être OTLP basé sur HTTP. gRPC est rejeté au moment de la configuration.
Déploiements directs (Amazon Bedrock, Google Vertex AI, passerelle)
Pour les déploiements qui s'authentifient auprès de votre propre fournisseur de modèle plutôt que Claude.ai, le point de terminaison du collecteur est fourni via l'un des trois canaux de configuration. Les trois utilisent les mêmes deux clés.
Recommandé : Utilisez le plugin claude-in-office pour Claude Code. Il vous guide dans la génération du manifeste, l'enregistrement des attributs d'extension Entra et la mise en place d'un point de terminaison d'amorçage avec otlp_endpoint et otlp_headers préconfigurés. Les trois canaux ci-dessous sont documentés à titre de référence et pour la configuration manuelle.
Clé | Format | Description |
| URL HTTPS | URL de base de votre collecteur OTLP. Le complément supprime les barres obliques finales et ajoute /v1/traces. |
| clé1=valeur1,clé2=valeur2 | En-têtes d'authentification optionnels. Même format que la variable d'environnement OTEL_EXPORTER_OTLP_HEADERS d'OpenTelemetry. |
Si otlp_endpoint n'est pas défini ou est vide, aucun collecteur personnalisé n'est configuré et le complément revient au comportement par défaut.
Remarque : Ces canaux de configuration s'appliquent uniquement aux déploiements Microsoft Office. Les compléments Google Workspace sont configurés séparément.
Canal 1 : Paramètre d'URL du manifeste
Ajoutez les clés en tant que paramètres de chaîne de requête à l'URL du volet des tâches dans votre manifeste de complément personnalisé :
Encodez les valeurs en URL. Cela applique la configuration à chaque utilisateur qui installe le manifeste.
Canal 2 : Extension d'annuaire Azure Entra ID
Pour une configuration par utilisateur, enregistrez les clés en tant qu'attributs d'extension d'annuaire Entra ID et assignez-les via Microsoft Graph. Le complément les lit à partir du jeton d'ID de l'utilisateur en utilisant l'authentification d'application imbriquée (NAA).
Les noms de revendication dans le jeton d'ID émis suivent le format d'extension d'annuaire Azure :
Revendication | Correspond à |
| otlp_endpoint |
| otlp_headers |
Définissez-les par utilisateur avec une opération PATCH Graph sur l'objet utilisateur. Azure encode les valeurs d'extension d'annuaire sous forme de tableaux à un seul élément dans le jeton d'ID ; le complément les déverrouille automatiquement. Ce canal nécessite entra_sso=1 dans les paramètres d'URL du manifeste pour activer l'acquisition de jeton NAA.
Canal 3 : Réponse du point de terminaison d'amorçage
Si votre déploiement utilise un point de terminaison d'amorçage (un point de terminaison JSON que votre organisation héberge et que le complément appelle au démarrage), incluez les clés dans le corps de la réponse :
{
"otlp_endpoint": "https://otel-collector.your-domain.com",
"otlp_headers": "Authorization=Bearer <token>"
}L'URL du point de terminaison d'amorçage elle-même est configurée via bootstrap_url dans les paramètres d'URL du manifeste ou une revendication Entra extn.bootstrap_url. Si un jeton d'ID Entra a été acquis, il est transmis au point de terminaison d'amorçage en tant qu'en-tête d'autorisation Bearer afin que votre point de terminaison puisse authentifier l'utilisateur avant de retourner la configuration par utilisateur.
Priorité
Lorsque plusieurs canaux fournissent une valeur, les canaux ultérieurs remplacent les canaux antérieurs : les paramètres du manifeste sont lus en premier, puis les revendications Entra, puis la réponse d'amorçage. La réponse d'amorçage l'emporte.
Si vous ne l'avez pas déjà fait, le chemin le plus rapide est le plugin claude-in-office.
Modes de déploiement
L'export du collecteur personnalisé est disponible sur les deux modes de déploiement :
Claude.ai Enterprise (OAuth) : piste d'audit complète incluant l'identité de l'utilisateur (
user.email,user.account_uuid,organization.id), les métadonnées du serveur MCP et les enregistrements de téléchargement de fichiers.Fournisseur direct (Bedrock, Vertex AI, passerelle) : piste d'audit principale (invites, entrées et sorties d'outils, URL de documents) mais pas d'identité utilisateur, pas de métadonnées MCP et pas d'intervalles de téléchargement de fichiers. L'attribution des utilisateurs nécessite de corréler
session.idpar rapport aux journaux de votre fournisseur d'identité.
La charge utile d'audit principale est identique dans les deux modes. Les déploiements de fournisseur direct manquent du contexte du compte Claude.ai, donc les attributs dérivés du profil utilisateur ou organisationnel Claude.ai sont absents. Consultez les balises [claude.ai-only] dans le schéma d'intervalle ci-dessous pour la liste complète.
Étiquettes de surface et de fournisseur
Chaque intervalle inclut deux étiquettes identifiant l'application Office et la plateforme qui l'ont généré. Utilisez-les comme vos dimensions principales pour le filtrage et les tableaux de bord.
Étiquette | Valeurs |
| sheet (Excel/Google Sheets), doc (Word), slide (PowerPoint) |
| m (Microsoft) |
Référence d'intervalle
Chaque tour d'utilisateur produit un arbre parent/enfant de jusqu'à cinq types d'intervalles. Les attributs marqués [content] contiennent des données générées par l'utilisateur ; ceux-ci forment votre charge utile d'audit. Les attributs marqués [claude.ai-only] sont remplis uniquement lorsque l'utilisateur se connecte avec un compte Claude ; ils sont absents sur les déploiements Bedrock, Vertex AI et passerelle. Les attributs absents sont omis de l'intervalle entièrement (pas de clé avec une valeur nulle).
L'intervalle file.upload et tous les attributs mcp.* sont également [claude.ai-only], car le téléchargement de fichiers et les connexions du serveur MCP sont des fonctionnalités de la plateforme Claude.
Pour les déploiements de fournisseur direct, l'identité de l'utilisateur doit être corrélée via session.id et document.url, jointe aux journaux de session de votre fournisseur d'identité.
Attributs de ressource
Ces attributs apparaissent sur chaque intervalle :
Attribut | Description |
| Valeur fixe : office-agent |
| Valeur fixe : 1.0.0 |
| Identifiant de commit de build |
agent.query (intervalle racine)
Un intervalle par tour d'utilisateur. C'est la racine de l'arbre d'intervalles et porte l'identité de session, le contexte du document et l'état du serveur MCP. SpanKind : INTERNAL.
Attribut | Description |
| sheet | doc | slide |
| m |
| L'invite de l'utilisateur (premiers 4000 caractères) |
| Identifiant de session opaque |
| Adresse e-mail de l'utilisateur |
| Compartiment de hachage déterministe (SHA-256 de l'e-mail, mod 30) |
| UUID du compte Claude |
| URL du document Office ouvert |
| UUID de l'organisation Claude |
| Niveau d'abonnement Claude |
| Type d'organisation Claude |
| Modèle sélectionné par l'utilisateur pour cette session |
| PC | Mac | OfficeOnline | iOS | Android | Universal |
| Numéro de build Office |
| Nombre de serveurs MCP configurés |
| Nombre de serveurs MCP connectés avec succès |
| Nombre de serveurs MCP dont la connexion a échoué |
| success | error | timeout | no_auth | not_attempted |
| Durée de récupération du registre MCP |
| Code de statut HTTP de récupération du registre MCP |
| Détails sérialisés du serveur MCP (noms, nombre d'outils, messages d'erreur) |
| Nombre de fichiers joints à ce tour |
| Nombre total d'octets téléchargés |
| Nombre de pièces jointes image |
| Nombre de pièces jointes document |
| Nombre d'autres pièces jointes |
| Nom de la classe d'exception (présent en cas d'échec) |
| Phase à laquelle la requête a échoué (présente en cas d'échec) |
agent.stream
Un span par appel API à Claude, en tant qu'enfant du span de requête. SpanKind : CLIENT.
Attribut | Description |
| ID du modèle utilisé pour cet appel |
| Nombre maximum de jetons de sortie demandés |
| Nombre de messages dans la conversation au démarrage du flux |
| Jetons d'entrée facturés (réponse API) |
| Jetons de sortie facturés (réponse API) |
| Jetons servis à partir du cache de prompt |
| Jetons écrits dans le cache de prompt |
| end_turn | tool_use | max_tokens | etc. |
| En-tête request-id de l'API Anthropic, utilisable pour la corrélation du support |
Remarque sur la mise en cache des prompts : Le complément demande la mise en cache des prompts sans condition. Les attributs cache_read_tokens et cache_creation_tokens sont définis à partir de la réponse API du fournisseur et sont omis lorsque la réponse ne les inclut pas. La mise en cache des prompts est disponible pour la plateforme Claude Developer ; à ce jour, Amazon Bedrock et Google Vertex AI ne retournent pas encore ces champs via le client utilisé par le complément. Lorsque le support sera disponible sur votre fournisseur, ces attributs commenceront à apparaître automatiquement.
agent.tool_execution
Une portée par appel d'outil, en tant qu'enfant de la portée de flux. SpanKind : INTERNAL. C'est l'enregistrement principal des actions que le modèle a entreprises sur le document.
Attribut | Description |
| Identifiant d'outil (par exemple get_cell_ranges, execute_office_js, edit_slide_xml) |
| ID unique de cet appel d'outil |
| serveur | client |
| first_party | mcp | serveur |
| lecture | écriture | lecture_écriture |
| manuel | auto_accept | différé |
| Entrée d'outil sérialisée (premiers 4000 caractères) |
| Booléen |
| Sortie d'outil sérialisée (premiers 4000 caractères) |
| Longueur complète de la sortie en caractères (utilisez pour détecter la troncature) |
| Classification d'erreur (présente en cas d'échec) |
| Cellules lues (surface de feuille uniquement) |
| Cellules écrites (surface de feuille uniquement) |
| Cellules copiées (surface de feuille uniquement) |
Remarque : L'attribut tool.accept_decision enregistre comment la décision d'autorisation a été prise : manuel (l'utilisateur a approuvé cette action spécifique), auto_accept (l'utilisateur avait précédemment accordé une approbation permanente), ou différé (l'action a été mise en file d'attente pour examen ultérieur). Utilisez ceci pour auditer les modèles d'approbation dans votre organisation.
agent.compaction
Un span par conversation pour l'auto-résumé, déclenché lorsque le contexte approche de la limite de fenêtre. SpanKind : CLIENT.
Attribut | Description |
| Nombre de jetons avant le résumé |
| Nombre de jetons après le résumé |
| Delta |
| Booléen |
| Actuellement toujours réactif |
Ce span porte également agent.surface, agent.vendor, session.id, user.email [claude.ai-only], user.bucket [claude.ai-only], office.platform et office.version, dupliqués à partir du span racine pour que vous puissiez interroger les événements de compaction indépendamment.
file.upload [claude.ai-only]
Un span par téléchargement de fichier individuel, en tant qu'enfant du span de requête. SpanKind : CLIENT. Ce type de span n'apparaît que lorsque les utilisateurs se connectent avec un compte Claude.ai. Le téléchargement de fichiers n'est pas disponible sur les déploiements de fournisseurs directs.
Attribut | Description |
| Nom de fichier original |
| Taille du fichier |
| Type MIME |
| Identifiant de l'API Anthropic Files |
| Booléen |
Événements de span
Les événements de span sont des marqueurs horodatés attachés aux spans ci-dessus. Ils capturent les transitions de cycle de vie et les signaux équivalents aux compteurs.
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}
Chaque compteur de produit interne enregistre également un événement de span portant le même nom sur le span actuellement actif, fournissant l'équivalent du flux de métriques dans vos données de trace. L'événement office_agent.token.usage est émis sur chaque span agent.stream, une fois par type de jeton non nul, avec les attributs {token_usage.type: input | output | cacheRead | cacheCreation, token_usage.model, token_usage.token_count}. Cela reflète la forme du compteur *.token.usage émise par d'autres produits Anthropic, de sorte qu'un collecteur unique peut agréger le coût des jetons entre les produits en regroupant sur service.name.
Comportement spécifique à la surface
Le schéma de télémétrie est cohérent sur toutes les surfaces. Voici les différences :
Feuilles (Excel) : les spans
agent.tool_executionincluent les attributssheet.cells_read,sheet.cells_writtenetsheet.cells_copied. Les événements de spanoffice_agent.cell_edit_collision_totalapparaissent lorsqu'un utilisateur est en train de modifier une cellule tandis qu'un outil tente d'écrire.Documents (Word) : les événements d'entonnoir d'édition de document suivent le cycle de vie de l'édition :
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. Pas d'attributssheet.cells_*.Diapositives (PowerPoint) : aucun attribut ou événement spécifique à la surface au-delà du schéma commun.
Reconstruction d'une session utilisateur
Déploiements Claude.ai
Filtrez les spans par
user.email(ouuser.account_uuid) etsession.id.Triez les spans
agent.querypar horodatage de début ; chacun est un tour utilisateur.Pour chaque tour,
user.messageest l'invite etdocument.urlest le fichier en cours de traitement.Les spans enfants
agent.tool_execution, triés par horodatage, sont les actions entreprises :tool.inputest ce qui a été tenté,tool.outputest le résultat,tool.accept_decisionenregistre si l'utilisateur a explicitement approuvé.
Déploiements de fournisseurs directs
Le complément n'a pas d'identité utilisateur Claude.ai dans ce mode, donc les spans ne portent pas user.email ou user.account_uuid. Pour attribuer l'activité à un utilisateur :
Filtrez les spans par
session.idpour isoler une session de complément continue.Utilisez
document.urlpour identifier le fichier en cours de traitement.Corrélez la session par rapport aux journaux de votre fournisseur d'identité : événements de connexion Entra, journaux d'accès de la passerelle ou journal des requêtes de votre point de terminaison d'amorçage (qui reçoit le jeton Entra ID de l'utilisateur en tant qu'en-tête Bearer).
Une fois qu'une session est attribuée à un utilisateur, la reconstruction par tour est identique : agent.query trié par horodatage, avec
user.message,tool.input,tool.outputettool.accept_decisionfournissant la piste d'audit.
Cela produit une transcription complète et ordonnée de l'interaction dans les deux modes de déploiement.