Surveillance

​

Démarrage rapide

# 1. Activer la télémétrie
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choisir les exportateurs (les deux sont facultatifs - configurez uniquement ce dont vous avez besoin)
export OTEL_METRICS_EXPORTER=otlp       # Options : otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Options : otlp, console, none

# 3. Configurer le point de terminaison OTLP (pour l'exportateur OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Définir l'authentification (si nécessaire)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Pour le débogage : réduire les intervalles d'export
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 secondes (par défaut : 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 secondes (par défaut : 5000ms)

# 6. Exécuter Claude Code
claude

​

Configuration de l’administrateur

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

​

Détails de la configuration

​

Variables de configuration courantes

​

Authentification mTLS

​

Contrôle de la cardinalité des métriques

​

Traces (bêta)

​

Hiérarchie des intervalles

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (nécessite un traçage bêta détaillé)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (outil Agent) intervalles claude_code.llm_request / claude_code.tool du sous-agent

​

Attributs des intervalles

​

En-têtes dynamiques

​

Configuration des paramètres

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​

Exigences du script

#!/bin/bash
# Exemple : plusieurs en-têtes
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

• La sortie /status
• Le journal de débogage, lors de l’exécution avec --debug ou après l’exécution de /debug dans la session
• stderr, dans les sessions non interactives démarrées avec -p

​

Comportement d’actualisation

​

Support des organisations multi-équipes

# Ajouter des attributs personnalisés pour l'identification de l'équipe
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

• Filtrer les métriques par équipe ou département
• Suivre les coûts par centre de coûts
• Créer des tableaux de bord spécifiques à l’équipe
• Configurer des alertes pour des équipes spécifiques

export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

Exemples de configurations

# Débogage de console (intervalles de 1 seconde)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Plusieurs exportateurs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Points de terminaison/backends différents pour les métriques et les journaux
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

# Métriques uniquement (pas d'événements/journaux)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Événements/journaux uniquement (pas de métriques)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

​

Métriques et événements disponibles

​

Attributs standard

• prompt.id : UUID corrélant une invite utilisateur avec tous les événements suivants jusqu’à l’invite suivante. Voir Attributs de corrélation d’événements.
• workspace.host_paths : répertoires d’espace de travail hôte sélectionnés dans l’application de bureau, sous forme de tableau de chaînes
• workflow.run_id : identifiant d’exécution, préfixé wf_, sur les événements d’API et d’outil émis par les agents qui appartiennent à une exécution d’outil Workflow. Le filtrage des événements par un workflow.run_id reconstruit les demandes d’API et les résultats d’outil de cette exécution. L’identifiant couvre les agents que le script de flux de travail génère et tous les agents que ceux-ci génèrent à leur tour, tels que les invocations de compétences. Il correspond à l’identifiant d’exécution signalé dans le résultat de l’outil Workflow. Absent sur tous les autres événements. Nécessite Claude Code v2.1.202 ou ultérieur
• workflow.name : nom du flux de travail, le meta.name de son script, émis aux côtés de workflow.run_id. Les noms de flux de travail intégrés apparaissent textuellement lorsque l’exécution exécute le script intégré non modifié. Les noms créés par l’utilisateur, y compris les copies modifiées de scripts intégrés, sont remplacés par custom sauf si OTEL_LOG_TOOL_DETAILS=1 est défini. Nécessite Claude Code v2.1.202 ou ultérieur

​

Métriques

​

Détails des métriques

​

Compteur de sessions

• Tous les attributs standard
• start_type : Comment la session a été démarrée. L’un de "fresh", "resume", "continue", ou "agents_view". La valeur "agents_view" identifie le processus du tableau de bord claude agents, une interface utilisateur locale lancée par l’utilisateur plutôt qu’une session conversationnelle. Filtrez sur cette valeur pour séparer les lancements de processus d’interface utilisateur des sessions conversationnelles dans vos tableaux de bord.

​

Compteur de lignes de code

• Tous les attributs standard
• type : ("added", "removed")
• model : Identifiant du modèle pour le modèle qui a effectué la modification (par exemple, « claude-sonnet-5 »)

​

Compteur de demandes de tirage

• Tous les attributs standard

​

Compteur de commits

• Tous les attributs standard

​

Compteur de coûts

• Tous les attributs standard
• model : Identifiant du modèle (par exemple, « claude-sonnet-5 »)
• query_source : Catégorie du sous-système qui a émis la demande. L’un de "main", "subagent", ou "auxiliary"
• speed : "fast" lorsque la demande a utilisé le mode rapide. Absent sinon
• effort : Niveau d’effort appliqué à la demande : "low", "medium", "high", "xhigh", ou "max". Absent lorsque le modèle ne supporte pas l’effort.
• agent.name : Type de sous-agent qui a émis la demande. Les noms d’agents intégrés et les agents des plugins de la place de marché officielle apparaissent textuellement. Les autres noms d’agents définis par l’utilisateur sont remplacés par "custom". Absent lorsque la demande n’a pas été émise par un type de sous-agent nommé.
• skill.name : Compétence active pour la demande, définie par l’outil Skill, une commande /, ou héritée par un sous-agent généré. Les noms de compétences intégrées, groupées, définies par l’utilisateur et de plugin de place de marché officielle apparaissent textuellement. Les noms de compétences de plugin tiers sont remplacés par "third-party". Absent lorsqu’aucune compétence n’est active.
• plugin.name : Plugin propriétaire lorsque la compétence active ou le sous-agent est fourni par un plugin. Les noms de plugins de place de marché officielle apparaissent textuellement. Les noms de plugins tiers sont remplacés par "third-party". Absent lorsque ni la compétence ni le sous-agent n’a de plugin propriétaire.
• marketplace.name : Place de marché à partir de laquelle le plugin propriétaire a été installé. Émis uniquement pour les plugins de place de marché officielle. Absent sinon.
• mcp_server.name : Serveur MCP dont l’outil a été exécuté dans le tour qui a produit cette demande. Les noms de serveurs intégrés, proxifiés par claude.ai et de registre officiel apparaissent textuellement. Les noms de serveurs configurés par l’utilisateur sont remplacés par "custom". Absent lorsqu’aucun outil MCP n’a été exécuté.
• mcp_tool.name : Outil MCP qui a été exécuté dans le tour qui a produit cette demande, avec la même rédaction que mcp_server.name. Absent lorsqu’aucun outil MCP n’a été exécuté.

​

Compteur de jetons

• Tous les attributs standard
• type : ("input", "output", "cacheRead", "cacheCreation")
• model : Identifiant du modèle (par exemple, « claude-sonnet-5 »)
• query_source : Catégorie du sous-système qui a émis la demande. L’un de "main", "subagent", ou "auxiliary"
• speed : "fast" lorsque la demande a utilisé le mode rapide. Absent sinon
• effort : Niveau d’effort appliqué à la demande. Voir Compteur de coûts pour les détails.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name : Attribution de compétence, plugin, agent et MCP pour la demande. Voir Compteur de coûts pour les définitions et le comportement de masquage.

​

Compteur de décisions de l’outil d’édition de code

• Tous les attributs standard
• tool_name : Nom de l’outil ("Edit", "Write", "NotebookEdit")
• decision : Décision de l’utilisateur ("accept", "reject")
• source : Source de la décision. L’un de "config", "hook", "user_permanent", "user_temporary", "user_abort", ou "user_reject". Voir l’Événement de décision d’outil pour savoir ce que chaque valeur signifie.
• language : Langage de programmation du fichier édité, tel que "TypeScript", "Python", "JavaScript", ou "Markdown". Retourne "unknown" pour les extensions de fichier non reconnues.

​

Compteur de temps actif

• Tous les attributs standard
• type : "user" pour les interactions au clavier, "cli" pour l’exécution d’outils et les réponses IA

​

Événements

​

Attributs de corrélation d’événements

​

Événement d’invite utilisateur

• Tous les attributs standard
• event.name : "user_prompt"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• prompt_length : Longueur de l’invite
• prompt : Contenu de l’invite. Masqué par défaut. Définissez OTEL_LOG_USER_PROMPTS=1 pour l’inclure
• command_name : Nom de la commande lorsque l’invite en invoque une. Les noms de commandes intégrées et groupées tels que compact ou debug sont émis tels quels ; les alias tels que reset émettent tels que tapés plutôt que le nom canonique. Les noms de commandes personnalisées, de plugin et MCP s’effondrent en custom ou mcp sauf si OTEL_LOG_TOOL_DETAILS=1 est défini
• command_source : Origine de la commande lorsqu’elle est présente : builtin, custom, ou mcp. Les commandes fournies par les plugins signalent comme custom

​

Événement de réponse d’assistant

• Tous les attributs standard
• event.name : "assistant_response"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• response_length : Longueur du texte de réponse en caractères
• response : Texte de réponse, tronqué à 60 Ko. Masqué à <REDACTED> par défaut. Définissez OTEL_LOG_ASSISTANT_RESPONSES=1 pour l’inclure. Lorsque OTEL_LOG_ASSISTANT_RESPONSES n’est pas défini, OTEL_LOG_USER_PROMPTS le contrôle à la place, donc définissez OTEL_LOG_ASSISTANT_RESPONSES=0 pour garder les réponses masquées tandis que la journalisation des invites est activée
• model : Identifiant du modèle (par exemple, « claude-sonnet-5 »)
• request_id : ID de demande d’API Anthropic de l’en-tête request-id de la réponse. Présent uniquement lorsque l’API en retourne un
• query_source : Sous-système qui a émis la demande, tel que "repl_main_thread", "compact", ou un nom de sous-agent

​

Événement de résultat d’outil

• Tous les attributs standard
• event.name : "tool_result"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• tool_name : Nom de l’outil
• tool_use_id : Identifiant unique pour cette invocation d’outil. Correspond au tool_use_id passé aux hooks, permettant la corrélation entre les événements OTel et les données capturées par les hooks.
• success : "true" ou "false"
• duration_ms : Temps d’exécution en millisecondes
• error_type : Chaîne de catégorie d’erreur lorsque l’outil a échoué, telle que "Error:ENOENT" ou "ShellError"
• error (lorsque OTEL_LOG_TOOL_DETAILS=1) : Message d’erreur complet lorsque l’outil a échoué
• decision_type : Toujours "accept", puisque cet événement n’est émis qu’après l’exécution de l’outil. Les appels rejetés ne produisent pas de résultat d’outil
• decision_source : Source de la décision de permission. L’un de "config", "hook", "user_permanent", ou "user_temporary". Voir l’Événement de décision d’outil pour savoir ce que chaque valeur signifie. Les sources de rejet uniquement "user_abort" et "user_reject" n’apparaissent jamais sur cet événement.
• tool_input_size_bytes : Taille de l’entrée d’outil sérialisée en JSON en octets
• tool_result_size_bytes : Taille du résultat de l’outil en octets
• mcp_server_scope : Identifiant de portée du serveur MCP (pour les outils MCP)
• tool_parameters (lorsque OTEL_LOG_TOOL_DETAILS=1) : Chaîne JSON contenant les paramètres spécifiques à l’outil :
  • Pour l’outil Bash : inclut bash_command, full_command, timeout, description, dangerouslyDisableSandbox, et git_commit_id (le SHA du commit, lorsqu’une commande git commit réussit)
  • Pour l’outil WorkspaceBash : inclut bash_command, full_command, timeout
  • Pour les outils MCP : inclut mcp_server_name, mcp_tool_name
  • Pour l’outil Skill : inclut skill_name
  • Pour l’outil Agent ou l’outil Task hérité : inclut subagent_type
• tool_input (lorsque OTEL_LOG_TOOL_DETAILS=1) : Arguments d’outil sérialisés en JSON. Les valeurs individuelles dépassant 512 caractères sont tronquées, et la charge utile complète est limitée à environ 4 K caractères. S’applique à tous les outils, y compris les outils MCP.

​

Événement de demande d’API

• Tous les attributs standard
• event.name : "api_request"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• model : Modèle utilisé (par exemple, « claude-sonnet-5 »)
• cost_usd : Coût estimé en USD
• duration_ms : Durée de la demande en millisecondes
• input_tokens : Nombre de jetons d’entrée
• output_tokens : Nombre de jetons de sortie
• cache_read_tokens : Nombre de jetons lus à partir du cache
• cache_creation_tokens : Nombre de jetons utilisés pour la création du cache
• request_id : ID de demande d’API Anthropic de l’en-tête request-id de la réponse, tel que "req_011...". Présent uniquement lorsque l’API en retourne un.
• speed : "fast" ou "normal", indiquant si le mode rapide était actif
• query_source : Sous-système qui a émis la demande, tel que "repl_main_thread", "compact", ou un nom de sous-agent
• effort : Niveau d’effort appliqué à la demande : "low", "medium", "high", "xhigh", ou "max". Absent lorsque le modèle ne supporte pas l’effort.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name : Attribution de compétence, plugin, agent et MCP pour la demande. Voir Compteur de coûts pour les définitions et le comportement de masquage.

​

Événement d’erreur d’API

• Tous les attributs standard
• event.name : "api_error"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• model : Modèle utilisé (par exemple, « claude-sonnet-5 »)
• error : Message d’erreur
• status_code : Code de statut HTTP sous forme de nombre. Absent pour les erreurs non-HTTP telles que les défaillances de connexion.
• duration_ms : Durée de la demande en millisecondes
• attempt : Nombre total de tentatives effectuées, y compris la demande initiale (1 signifie qu’aucune nouvelle tentative ne s’est produite)
• request_id : ID de demande d’API Anthropic de l’en-tête request-id de la réponse, tel que "req_011...". Présent uniquement lorsque l’API en retourne un.
• speed : "fast" ou "normal", indiquant si le mode rapide était actif
• query_source : Sous-système qui a émis la demande, tel que "repl_main_thread", "compact", ou un nom de sous-agent
• effort : Niveau d’effort appliqué à la demande. Absent lorsque le modèle ne supporte pas l’effort.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name : Attribution de compétence, plugin, agent et MCP pour la demande. Voir Compteur de coûts pour les définitions et le comportement de masquage.

​

Événement de refus d’API

• Tous les attributs standard
• event.name : "api_refusal"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• model : Identifiant du modèle de la demande
• request_id : ID de demande d’API Anthropic de l’en-tête request-id de la réponse, tel que "req_011...". Présent uniquement lorsque l’API en retourne un.
• query_source : Sous-système qui a émis la demande, tel que "repl_main_thread", "compact", ou un nom de sous-agent. Voir api_request pour les définitions.
• speed : Soit "fast" lorsque le Mode rapide est actif, soit "normal"
• attempt : Numéro de tentative de nouvelle tentative. La première tentative est 1.
• effort : Niveau d’effort appliqué à la demande. Absent lorsque le modèle ne supporte pas l’effort.
• server_fallback_hop : true lorsque le basculement de modèle côté serveur de l’API a déjà réessayé ce refus sur un modèle différent, donc l’utilisateur n’a pas vu ce refus particulier. false lorsque la demande s’est terminée par un refus. Un seul tour peut émettre à la fois un événement true hop et un événement final false ultérieur lorsque le modèle de secours refuse également.
• has_category : true lorsque la réponse de l’API contenait une stop_details.category de "cyber", "bio", "frontier_llm", ou "reasoning_extraction". false lorsque la réponse ne contenait aucune catégorie ou une valeur en dehors de cet ensemble. Absent lorsque server_fallback_hop est true, car les blocs hop ne portent pas stop_details.
• has_explanation : true lorsque la réponse de l’API contenait une stop_details.explanation, sinon false. Absent lorsque server_fallback_hop est true.
• category : La valeur stop_details.category de la réponse de l’API. L’un de "cyber", "bio", "frontier_llm", ou "reasoning_extraction". Présent uniquement lorsque OTEL_LOG_TOOL_DETAILS=1 est défini et has_category est true.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name : Attribution de compétence, plugin, agent et MCP pour la demande. Voir Compteur de coûts pour les définitions et le comportement de masquage.

​

Événement de corps de demande d’API

• Tous les attributs standard
• event.name : "api_request_body"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• body : Paramètres de demande de l’API Messages sérialisés en JSON (invite système, messages, outils, etc.), tronqués à 60 Ko. Le contenu de la réflexion étendue dans les tours d’assistant antérieurs est masqué. Émis uniquement en mode en ligne (OTEL_LOG_RAW_API_BODIES=1).
• body_ref : Chemin absolu vers un fichier <dir>/<uuid>.request.json contenant le corps non tronqué. Émis uniquement en mode fichier (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length : Longueur du corps non tronqué. Octets UTF-8 lorsque OTEL_LOG_RAW_API_BODIES=file:<dir>, ou unités de code UTF-16 lorsque =1
• body_truncated : "true" lorsque la troncature en ligne s’est produite. Absent en mode fichier et lorsqu’aucune troncature ne s’est produite.
• model : Identifiant du modèle à partir des paramètres de demande
• query_source : Sous-système qui a émis la demande (par exemple, "compact")

​

Événement de corps de réponse d’API

• Tous les attributs standard
• event.name : "api_response_body"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• body : Réponse de l’API Messages sérialisée en JSON (id, blocs de contenu, utilisation, raison d’arrêt), tronquée à 60 Ko. Le contenu de la réflexion étendue est masqué. Émis uniquement en mode en ligne (OTEL_LOG_RAW_API_BODIES=1).
• body_ref : Chemin absolu vers un fichier <dir>/<request_id>.response.json contenant le corps non tronqué. Émis uniquement en mode fichier (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length : Longueur du corps non tronqué. Octets UTF-8 lorsque OTEL_LOG_RAW_API_BODIES=file:<dir>, ou unités de code UTF-16 lorsque =1
• body_truncated : "true" lorsque la troncature en ligne s’est produite. Absent en mode fichier et lorsqu’aucune troncature ne s’est produite.
• model : Identifiant du modèle
• query_source : Sous-système qui a émis la demande
• request_id : ID de demande d’API Anthropic de l’en-tête request-id de la réponse, tel que "req_011...". Présent uniquement lorsque l’API en retourne un.

​

Événement de décision d’outil

• Tous les attributs standard
• event.name : "tool_decision"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• tool_name : Nom de l’outil (par exemple, « Read », « Edit », « Write », « NotebookEdit »)
• tool_use_id : Identifiant unique pour cette invocation d’outil. Correspond au tool_use_id passé aux hooks, permettant la corrélation entre les événements OTel et les données capturées par les hooks.
• decision : Soit "accept" soit "reject"
• source : Source de la décision :
  • "config" : Décidé automatiquement sans invite, basé sur les paramètres du projet, les règles d’autorisation dans les paramètres personnels de l’utilisateur, la politique gérée par l’entreprise, les drapeaux --allowedTools ou --disallowedTools, le mode de permission actif, une autorisation limitée à la session d’une invite antérieure dans la même session CLI interactive, ou parce que l’outil est intrinsèquement sûr. L’événement n’indique pas laquelle de ces sources a correspondu.
  • "hook" : Un hook PreToolUse ou PermissionRequest a retourné la décision.
  • "user_permanent" : Émis lorsque l’utilisateur a choisi « Oui, et ne me demande plus pour … » à une invite de permission, ce qui enregistre une règle d’autorisation dans ses paramètres personnels. Dans la CLI interactive, ceci est émis uniquement pour ce choix lui-même ; les appels ultérieurs qui correspondent à la règle enregistrée émettent "config" à la place. Dans le SDK Agent ou les sessions -p non-interactives, à la fois le choix initial et les correspondances de règles ultérieures émettent "user_permanent". Traité comme une acceptation.
  • "user_temporary" : Émis lorsque l’utilisateur a choisi « Oui » à une invite de permission pour une approbation unique, ou a choisi l’une des options « … pendant cette session » sur une invite d’édition ou de lecture de fichier. Dans la CLI interactive, ceci est émis uniquement pour le choix lui-même ; les appels ultérieurs autorisés par cette autorisation limitée à la session émettent "config" à la place. Dans le SDK Agent ou les sessions -p non-interactives, à la fois le choix et les correspondances ultérieures émettent "user_temporary". Traité comme une acceptation.
  • "user_abort" : Émis lorsque l’utilisateur a fermé l’invite de permission sans répondre. Traité comme un rejet.
  • "user_reject" : Émis lorsque l’utilisateur a choisi « Non » lorsqu’il a été invité. Dans la CLI interactive, ceci est émis uniquement pour ce choix lui-même ; les appels qui correspondent à une règle de refus dans les paramètres personnels de l’utilisateur émettent "config" à la place. Dans le SDK Agent ou les sessions -p non-interactives, les appels qui correspondent à une règle de refus dans les paramètres personnels émettent "user_reject". Traité comme un rejet.
• tool_parameters (lorsque OTEL_LOG_TOOL_DETAILS=1) : Chaîne JSON contenant les paramètres spécifiques à l’outil. Même forme que l’Événement de résultat d’outil, moins les champs post-exécution tels que git_commit_id. Les valeurs peuvent différer de tool_result pour un appel accepté si la décision de permission réécrit l’entrée d’outil via updatedInput. Utilisez cet attribut pour voir quelle commande a été rejetée lorsque decision est "reject".
  • Pour l’outil Bash : inclut bash_command, full_command, timeout, description, dangerouslyDisableSandbox
  • Pour l’outil WorkspaceBash : inclut bash_command, full_command, timeout
  • Pour les outils MCP : inclut mcp_server_name, mcp_tool_name
  • Pour l’outil Skill : inclut skill_name
  • Pour l’outil Agent ou l’outil Task hérité : inclut subagent_type

​

Événement de changement de mode de permission

• Tous les attributs standard
• event.name : "permission_mode_changed"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• from_mode : Le mode de permission précédent, par exemple "default", "plan", "acceptEdits", "auto", ou "bypassPermissions"
• to_mode : Le nouveau mode de permission
• trigger : Ce qui a causé le changement. L’un de "shift_tab", "exit_plan_mode", "auto_gate_denied", ou "auto_opt_in". Absent lorsque la transition provient du SDK ou du pont

​

Événement d’authentification

• Tous les attributs standard
• event.name : "auth"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• action : "login" ou "logout"
• success : "true" ou "false"
• auth_method : Méthode d’authentification, telle que "oauth"
• error_category : Type d’erreur catégorique lorsque l’action a échoué. Le message d’erreur brut n’est jamais inclus
• status_code : Code de statut HTTP sous forme de chaîne lorsque l’action a échoué avec une erreur HTTP

​

Événement de connexion du serveur MCP

• Tous les attributs standard
• event.name : "mcp_server_connection"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• status : "connected", "failed", ou "disconnected"
• transport_type : Transport du serveur, tel que "stdio", "sse", ou "http"
• server_scope : Portée à laquelle le serveur est configuré, telle que "user", "project", ou "local"
• duration_ms : Durée de la tentative de connexion en millisecondes
• error_code : Code d’erreur lorsque la connexion a échoué
• is_plugin : true lorsque le serveur est fourni par un plugin, false sinon
• plugin_id_hash (lorsque is_plugin est true) : Hash stable du nom du plugin et de la place de marché, pour regrouper les événements par plugin sans exposer le nom
• plugin.name (lorsque is_plugin est true) : Nom du plugin qui fournit le serveur. Pour les plugins tiers, ceci est la chaîne littérale "third-party" sauf si OTEL_LOG_TOOL_DETAILS=1 ; cela protège les noms de plugins tiers d’apparaître dans les journaux par défaut. Les plugins provenant de sources officielles d’Anthropic sont toujours identifiés par nom. Les attributs plugin_id_hash et plugin.name circulent vers votre propre backend de surveillance et ne sont pas envoyés à Anthropic
• server_name (lorsque OTEL_LOG_TOOL_DETAILS=1) : Nom du serveur configuré
• error (lorsque OTEL_LOG_TOOL_DETAILS=1) : Message d’erreur complet lorsque la connexion a échoué

​

Événement d’erreur interne

• Tous les attributs standard
• event.name : "internal_error"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• error_name : Nom de la classe d’erreur, tel que "TypeError" ou "SyntaxError"
• error_code : Code errno Node.js tel que "ENOENT" lorsqu’il est présent sur l’erreur

​

Événement de plugin installé

• Tous les attributs standard
• event.name : "plugin_installed"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• marketplace.is_official : "true" si la place de marché est une place de marché officielle d’Anthropic, "false" sinon
• install.trigger : "cli" ou "ui"
• plugin.name : Nom du plugin installé. Pour les places de marché tierces, ceci est inclus uniquement lorsque OTEL_LOG_TOOL_DETAILS=1
• plugin.version : Version du plugin lorsqu’elle est déclarée dans l’entrée de la place de marché. Pour les places de marché tierces, ceci est inclus uniquement lorsque OTEL_LOG_TOOL_DETAILS=1
• marketplace.name : Place de marché à partir de laquelle le plugin a été installé. Pour les places de marché tierces, ceci est inclus uniquement lorsque OTEL_LOG_TOOL_DETAILS=1

​

Événement de plugin chargé

• Tous les attributs standard
• event.name : "plugin_loaded"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• plugin.name : nom du plugin. Pour les plugins en dehors de la place de marché officielle et du bundle intégré, la valeur est "third-party" sauf si OTEL_LOG_TOOL_DETAILS=1
• marketplace.name : place de marché à partir de laquelle le plugin a été installé, lorsqu’elle est connue. Masquée à "third-party" sous la même condition que plugin.name
• plugin.version : version du manifeste du plugin. Inclus uniquement lorsque le nom n’est pas masqué et que le manifeste déclare une version
• plugin.scope : catégorie de provenance du plugin : "official", "org", "user-local", ou "default-bundle"
• enabled_via : comment le plugin en est venu à être activé : "default-enable", "org-policy", "seed-mount", ou "user-install"
• plugin_id_hash : hash déterministe du nom du plugin et de la place de marché, envoyé uniquement à votre exportateur configuré. Vous permet de compter combien de plugins tiers distincts sont chargés dans votre flotte sans enregistrer leurs noms
• has_hooks : si le plugin contribue des hooks
• has_mcp : si le plugin contribue des serveurs MCP
• host_owned_mcp : true lorsque l’hôte SDK gère les connexions MCP de ce plugin et Claude Code a ignoré la lecture de la configuration du serveur MCP du plugin, false sinon. Nécessite Claude Code v2.1.172 ou ultérieur
• skill_path_count : nombre de répertoires de compétences que le plugin déclare
• command_path_count : nombre de répertoires de commandes que le plugin déclare
• agent_path_count : nombre de répertoires d’agents que le plugin déclare
• safe_mode : "true" lorsque la session a été démarrée avec --safe-mode, "false" sinon. En mode sûr, cet événement rapporte l’inventaire configuré uniquement ; les commandes, compétences, hooks et serveurs MCP du plugin ne se chargent pas. Nécessite Claude Code v2.1.169 ou ultérieur

​

Événement de compétence activée

• Tous les attributs standard
• event.name : "skill_activated"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• skill.name : Nom de la compétence. Pour les compétences définies par l’utilisateur et les compétences de plugin tiers, la valeur est l’espace réservé "custom_skill" sauf si OTEL_LOG_TOOL_DETAILS=1
• invocation_trigger : Comment la compétence a été déclenchée ("user-slash", "claude-proactive", ou "nested-skill")
• skill.source : D’où la compétence a été chargée (par exemple, "bundled", "userSettings", "projectSettings", "plugin")
• skill.kind : "workflow" lorsque la compétence est une compétence de flux de travail. Absent sinon
• plugin.name (lorsque OTEL_LOG_TOOL_DETAILS=1 ou le plugin provient d’une place de marché officielle) : Nom du plugin propriétaire lorsque la compétence est fournie par un plugin
• marketplace.name (lorsque OTEL_LOG_TOOL_DETAILS=1 ou le plugin provient d’une place de marché officielle) : Place de marché du plugin propriétaire, lorsque la compétence est fournie par un plugin

​

Événement de mention @

• Tous les attributs standard
• event.name : "at_mention"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• mention_type : Type de mention ("file", "directory", "agent", "mcp_resource")
• success : Si la mention a été résolue avec succès ("true" ou "false")

​

Événement de tentatives d’API épuisées

• Tous les attributs standard
• event.name : "api_retries_exhausted"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• model : Modèle utilisé
• error : Message d’erreur final
• status_code : Code de statut HTTP sous forme de nombre. Absent pour les erreurs non-HTTP.
• total_attempts : Nombre total de tentatives effectuées
• total_retry_duration_ms : Temps mural total sur toutes les tentatives
• speed : "fast" ou "normal"

​

Événement de hook enregistré

• Tous les attributs standard
• event.name : "hook_registered"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• hook_event : type d’événement hook, tel que "PreToolUse" ou "PostToolUse"
• hook_type : type d’implémentation du hook : "command", "prompt", "mcp_tool", "http", ou "agent"
• hook_source : où le hook est défini : "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings", ou "pluginHook"
• safe_mode : "true" lorsque la session a été démarrée avec --safe-mode, "false" sinon. Nécessite Claude Code v2.1.169 ou ultérieur
• hook_matcher (lorsque OTEL_LOG_TOOL_DETAILS=1) : la chaîne matcher de la configuration du hook, lorsqu’elle est définie
• plugin.name (lorsque hook_source est "pluginHook") : nom du plugin contributeur. Pour les plugins en dehors de la place de marché officielle et du bundle intégré, la valeur est "third-party" sauf si OTEL_LOG_TOOL_DETAILS=1
• plugin_id_hash (lorsque hook_source est "pluginHook") : hash déterministe du nom du plugin et de la place de marché, envoyé uniquement à votre exportateur configuré. Vous permet de compter les plugins contributeurs distincts sans enregistrer leurs noms

​

Événement de démarrage d’exécution de hook

• Tous les attributs standard
• event.name : "hook_execution_start"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• hook_event : Type d’événement hook, tel que "PreToolUse" ou "PostToolUse"
• hook_name : Nom complet du hook incluant le matcher, tel que "PreToolUse:Write"
• num_hooks : Nombre de commandes hook correspondantes
• managed_only : "true" lorsque seuls les hooks de politique gérée sont autorisés
• hook_source : "policySettings" ou "merged"
• safe_mode : "true" lorsque la session a été démarrée avec --safe-mode, "false" sinon. Nécessite Claude Code v2.1.169 ou ultérieur
• hook_definitions : Configuration du hook sérialisée en JSON. Inclus uniquement lorsque le traçage bêta détaillé et OTEL_LOG_TOOL_DETAILS=1 sont tous deux activés

​

Événement de fin d’exécution de hook

• Tous les attributs standard
• event.name : "hook_execution_complete"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• hook_event : Type d’événement hook
• hook_name : Nom complet du hook incluant le matcher
• num_hooks : Nombre de commandes hook correspondantes
• num_success : Nombre qui se sont terminées avec succès
• num_blocking : Nombre qui ont retourné une décision de blocage
• num_non_blocking_error : Nombre qui ont échoué sans bloquer
• num_cancelled : Nombre annulé avant la fin
• total_duration_ms : Durée murale de tous les hooks correspondants
• managed_only : "true" lorsque seuls les hooks de politique gérée sont autorisés
• hook_source : "policySettings" ou "merged"
• safe_mode : "true" lorsque la session a été démarrée avec --safe-mode, "false" sinon. Nécessite Claude Code v2.1.169 ou ultérieur
• hook_definitions : Configuration du hook sérialisée en JSON. Inclus uniquement lorsque le traçage bêta détaillé et OTEL_LOG_TOOL_DETAILS=1 sont tous deux activés

​

Événement de métriques de plugin hook

• Tous les attributs standard
• event.name : "hook_plugin_metrics"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• plugin_id : identifiant du plugin sous la forme <name>@<marketplace>
• hook_event : type d’événement hook qui a émis les métriques
• Jusqu’à 20 clés de métriques émises par le plugin. Les noms correspondent à ^[a-z][a-z0-9_]{0,39}$. Les valeurs sont booléennes ou numériques.

​

Événement de compaction

• Tous les attributs standard
• event.name : "compaction"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• trigger : "auto" ou "manual"
• success : "true" ou "false"
• duration_ms : Durée de la compaction
• pre_tokens : Nombre approximatif de jetons avant la compaction
• post_tokens : Nombre approximatif de jetons après la compaction
• error : Message d’erreur lorsque la compaction a échoué
• precompute_reuse : Défini uniquement lorsque trigger est "manual". La compaction automatique peut préparer un résumé en arrière-plan avant que la fenêtre de contexte ne se remplisse, et cet attribut enregistre si /compact a réutilisé ce résumé préparé. "hit" signifie qu’il a été réutilisé ; "miss_custom_instructions", "miss_hook", et "miss_not_ready" donnent la raison pour laquelle un résumé frais a été calculé à la place. Nécessite Claude Code v2.1.153 ou ultérieur

​

Événement de sondage de rétroaction

• Tous les attributs standard
• event.name : "feedback_survey"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• event_type : Événement du cycle de vie du sondage, par exemple "appeared", "responded", ou "transcript_prompt_appeared"
• appearance_id : ID unique liant les événements émis pour une instance de sondage
• survey_type : Quel sondage a produit l’événement. "session" est l’invite d’évaluation « Comment Claude se débrouille-t-il ? »
• response : La sélection de l’utilisateur sur les événements responded
• enabled_via_override : true lorsque CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL est défini. Émis en tant que booléen, pas une chaîne. Présent sur les événements de sondage session. Filtrez sur cet attribut pour confirmer que le remplacement est appliqué dans votre flotte

​

Interpréter les données de métriques et d’événements

​

Surveillance de l’utilisation

​

Surveillance des coûts

• Suivre les tendances d’utilisation entre les équipes ou les individus
• Identifier les sessions à utilisation élevée pour l’optimisation
• Attribuer les dépenses à des compétences, des plugins ou des types de sous-agents spécifiques via les attributs skill.name, plugin.name, et agent.name

​

Alertes et segmentation

• Pics de coûts
• Consommation de jetons inhabituelle
• Volume de session élevé d’utilisateurs spécifiques

​

Détecter l’épuisement des tentatives

​

Analyse des événements

• Les outils les plus fréquemment utilisés
• Les taux de réussite des outils
• Les temps d’exécution moyens des outils
• Les modèles d’erreur par type d’outil

​

Audit des événements de sécurité

​

Attribuer les actions aux utilisateurs

export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

​

Audit de l’activité MCP

• tool_result : conserve tool_name et mcp_server_scope, omet mcp_server_name, mcp_tool_name, et les arguments
• tool_decision : conserve tool_name, omet tool_parameters
• mcp_server_connection : omet server_name et le message d’erreur, mais conserve is_plugin, plugin_id_hash, et plugin.name, avec les noms de plugins non-Anthropic redactés au littéral "third-party", de sorte que les serveurs fournis par les plugins restent distinguables sans journalisation détaillée

​

Mapper les questions de sécurité aux événements

​

Envoyer les événements à un SIEM

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

​

Considérations relatives aux backends

​

Pour les métriques

• Bases de données de séries chronologiques (par exemple, Prometheus) : Calculs de taux, métriques agrégées
• Magasins colonnaires (par exemple, ClickHouse) : Requêtes complexes, analyse d’utilisateurs uniques
• Plates-formes d’observabilité complètes (par exemple, Honeycomb, Datadog, Grafana Cloud) : Requêtes avancées, visualisation, alertes

​

Pour les événements/journaux

• Systèmes d’agrégation de journaux (par exemple, Elasticsearch, Loki) : Recherche en texte intégral, analyse de journaux
• Magasins colonnaires (par exemple, ClickHouse) : Analyse d’événements structurés
• Plates-formes d’observabilité complètes (par exemple, Honeycomb, Datadog, Grafana Cloud) : Corrélation entre les métriques et les événements

​

Pour les traces

• Systèmes de traçage distribué (par exemple, Jaeger, Zipkin, Grafana Tempo) : Visualisation d’intervalles, cascades de demandes, analyse de latence
• Plates-formes d’observabilité complètes (par exemple, Honeycomb, Datadog, Grafana Cloud) : Recherche de traces et corrélation avec les métriques et les journaux

​

Informations sur le service

• service.name : claude-code
• service.version : Version actuelle de Claude Code
• os.type : Type de système d’exploitation (par exemple, linux, darwin, windows)
• os.version : Chaîne de version du système d’exploitation
• host.arch : Architecture de l’hôte (par exemple, amd64, arm64)
• wsl.version : Numéro de version WSL (présent uniquement lors de l’exécution sur Windows Subsystem for Linux)
• Nom du compteur : com.anthropic.claude_code

​

Ressources de mesure du ROI

​

Sécurité et confidentialité

• L’export OpenTelemetry vers votre backend est opt-in et nécessite une configuration explicite. Pour la télémétrie opérationnelle distincte d’Anthropic et comment la désactiver, consultez Utilisation des données
• Les contenus de fichiers bruts et les extraits de code ne sont pas inclus dans les métriques ou les événements. Les intervalles de trace constituent un chemin de données distinct : voir la puce OTEL_LOG_TOOL_CONTENT ci-dessous
• Lorsqu’authentifié via OAuth, user.email est inclus dans les attributs de télémétrie. Si cela pose un problème pour votre organisation, travaillez avec votre backend de télémétrie pour filtrer ou masquer ce champ
• Le contenu des invites utilisateur n’est pas collecté par défaut. Seule la longueur de l’invite est enregistrée. Pour inclure le contenu de l’invite, définissez OTEL_LOG_USER_PROMPTS=1
• Le texte de réponse de l’assistant n’est pas collecté par défaut. Seule la longueur de la réponse est enregistrée. Pour inclure le texte de réponse, définissez OTEL_LOG_ASSISTANT_RESPONSES=1. Comme toutes les données OpenTelemetry de Claude Code, le texte de réponse est envoyé uniquement au point de terminaison OTel que vous configurez, jamais à Anthropic. Lorsque cette variable n’est pas définie, OTEL_LOG_USER_PROMPTS est utilisé comme solution de secours, donc définissez OTEL_LOG_ASSISTANT_RESPONSES=0 si vous souhaitez le contenu de l’invite sans contenu de réponse
• Les arguments d’entrée d’outil et les paramètres ne sont pas enregistrés par défaut. Pour les inclure, définissez OTEL_LOG_TOOL_DETAILS=1. Ces données sont envoyées uniquement au point de terminaison OTEL que vous configurez, jamais à Anthropic. Les arguments peuvent toujours contenir des valeurs sensibles, donc configurez votre backend de télémétrie pour filtrer ou masquer ces attributs selon les besoins. Lorsqu’activé :
  • Les événements tool_result et tool_decision incluent un attribut tool_parameters avec les commandes Bash, les noms de serveur MCP et d’outil, et les noms de compétences. Les champs tels que full_command sont émis sans troncature
  • Les événements tool_result incluent également un attribut tool_input avec les chemins de fichiers, les URL, les modèles de recherche et d’autres arguments. Les valeurs individuelles dépassant 512 caractères sont tronquées et le total est limité à environ 4 K caractères
  • Les événements user_prompt incluent le command_name verbatim pour les commandes personnalisées, de plugin et MCP
  • Les intervalles de trace incluent le même attribut tool_input et les attributs dérivés de l’entrée tels que file_path, avec la même troncature que tool_input
• Le contenu d’entrée et de sortie d’outil n’est pas enregistré dans les intervalles de trace par défaut. Pour l’inclure, définissez OTEL_LOG_TOOL_CONTENT=1. Lorsqu’activé, les événements d’intervalle incluent le contenu complet d’entrée et de sortie d’outil tronqué à 60 Ko par intervalle. Cela peut inclure les contenus de fichiers bruts des résultats de l’outil Read et la sortie de commande Bash. Configurez votre backend de télémétrie pour filtrer ou masquer ces attributs selon les besoins
• Les corps bruts de la demande et de la réponse de l’API Messages d’Anthropic ne sont pas enregistrés par défaut. Pour les inclure, définissez OTEL_LOG_RAW_API_BODIES. Avec =1, chaque appel d’API émet des événements de journaux api_request_body et api_response_body dont l’attribut body est la charge utile sérialisée en JSON, tronquée à 60 Ko. Avec =file:<dir>, les corps non tronqués sont écrits dans les fichiers .request.json et .response.json sous ce répertoire et les événements portent un chemin body_ref à la place du corps en ligne. Livrez le répertoire avec un collecteur de journaux ou un sidecar plutôt que via le flux de télémétrie. Dans les deux modes, les corps contiennent l’historique complet de la conversation (invite système, chaque tour d’utilisateur et d’assistant antérieur, résultats d’outils), donc l’activation de cette option implique le consentement à tout ce que les autres drapeaux de contenu OTEL_LOG_* révèleraient. Le contenu de réflexion étendue de Claude est toujours masqué de ces corps indépendamment des autres paramètres

​

Surveiller Claude Code sur Amazon Bedrock