OpenTelemetry permet de suivre une activité sans enregistrer systématiquement les conversations. Cet atelier collecte d’abord les métriques de requêtes, de durée, de sessions ou de consommation de tokens. Les logs des agents restent désactivés. Une sonde fictive vérifie séparément leur chemin de réception, sans envoyer de prompt, de commande d’agent ou de secret.
Configuration vérifiée dans les documentations officielles le 20 novembre 2026. Prévoyez un serveur Linux de test avec Docker et curl, ainsi que des CLI récents lorsque vous déciderez de les raccorder. Utilisez un compte système d’essai sans configuration administrée contradictoire, un dépôt fictif et un terminal dédié. Ne copiez ni clés ni historique de travail.
- Codex et Claude CodeChaque client émet les métriques d’activité qu’il prend en charge.
- OTLP sur HTTPLes métriques et la sonde de journaux ont chacune leur route sur la boucle locale.
- OpenTelemetry CollectorLa sortie de diagnostic résume les lots reçus.
- VérificationEnvoie les sondes puis démarre une session par client pour confirmer la réception.
Le guide suivant ajoute l’historique dans Prometheus et les graphiques dans Grafana. Installer Agent Deck et Grafana sur un serveur.
1. Comprendre ce que l’on mesure
Codex sépare les exporteurs de logs, métriques et traces dans sa configuration OTel. Claude Code utilise des variables distinctes par signal. Un journal décrit un événement. Une métrique compte ou mesure. Vérifiez ensuite le résultat avec le diff et les tests du projet.
Faites défiler le tableau horizontalement pour lire les deux colonnes.
| Signal | Ce qu’il mesure |
|---|---|
Codex · codex.api_request et codex.api_request.duration_ms |
Volume et durée des requêtes, y compris les reprises éventuelles. |
Codex · codex.tool.call |
Nombre d’appels et résultat par outil. Le champ tool donne le nom de l’outil. |
Claude Code · claude_code.session.count |
Nombre de sessions commencées. |
Claude Code · claude_code.token.usage et claude_code.cost.usage |
Consommation de tokens et estimation du coût. |
2. Préparer un Collector limité au serveur d’essai
Créez otel-collector.yaml avec cette configuration. L’image est figée sur la version publiée 0.165.0. Le récepteur HTTP écoute uniquement sur la boucle locale. Le port 8888 expose les métriques internes du Collector, également en boucle locale. Il renseigne sur le récepteur et les lots traités.
receivers:
otlp:
protocols:
http:
endpoint: 127.0.0.1:4318
processors:
batch:
timeout: 1s
exporters:
debug:
verbosity: basic
service:
telemetry:
metrics:
readers:
- pull:
exporter:
prometheus:
host: 127.0.0.1
port: 8888
pipelines:
metrics:
receivers: [otlp]
processors: [batch]
exporters: [debug]
logs:
receivers: [otlp]
processors: [batch]
exporters: [debug]
La commande validate vérifie la configuration sans démarrer le récepteur. Après validation, démarrez le conteneur au premier plan. Avec Docker Engine et le réseau host sur le serveur Linux, le Collector et les CLI partagent la même boucle locale.
docker run --rm --network none \
--mount "type=bind,src=$PWD/otel-collector.yaml,dst=/etc/otelcol/config.yaml,readonly" \
otel/opentelemetry-collector:0.165.0 validate --config=/etc/otelcol/config.yaml
docker run --rm --name atelier-otel --network host --log-driver=none \
--mount "type=bind,src=$PWD/otel-collector.yaml,dst=/etc/otelcol/config.yaml,readonly" \
otel/opentelemetry-collector:0.165.0 --config=/etc/otelcol/config.yaml
L’exporteur debug en verbosity basic affiche un résumé de chaque lot dans le terminal. Le conteneur reste au premier plan et s’arrête à la fermeture. Le pilote de journalisation Docker est désactivé pour cet exercice.
3. Raccorder Codex en mode métriques
Dans le fichier utilisateur ~/.codex/config.toml du compte d’essai, ou celui du CODEX_HOME dédié, adaptez les tables existantes plutôt que les dupliquer. Ne placez pas ces réglages dans le dépôt fictif. La référence et le schéma officiels distinguent bien exporter pour les logs et metrics_exporter pour les métriques. Une destination HTTP spécifique reçoit le chemin complet du signal.
[analytics]
enabled = false
[otel]
environment = "atelier-local"
exporter = "none"
trace_exporter = "none"
metrics_exporter = { otlp-http = { endpoint = "http://127.0.0.1:4318/v1/metrics", protocol = "binary" } }
log_user_prompt = false
log_agent_responses = false
log_guardian_assessments = false
log_sse_deltas = false
tool_result = { max_bytes = 0 }
Le réglage analytics désactive l’exporteur analytique intégré ; l’export OTLP explicitement configuré reste indépendant. Ces options ne rendent pas les appels aux modèles locaux. Elles ne modifient ici que la destination de télémétrie choisie.
4. Raccorder Claude Code dans le terminal d’essai
Les variables suivantes ciblent le même récepteur en HTTP/protobuf. Elles réduisent les détails et certains identifiants. Gardez cette configuration dans le terminal dédié, sans l’inscrire globalement dans le profil de connexion. Vérifiez les versions et les règles administrées avant l’essai, car ces règles peuvent imposer d’autres réglages.
unset BETA_TRACING_ENDPOINT OTEL_RESOURCE_ATTRIBUTES
unset OTEL_EXPORTER_OTLP_HEADERS
unset OTEL_EXPORTER_OTLP_METRICS_HEADERS OTEL_EXPORTER_OTLP_LOGS_HEADERS
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=none
export OTEL_TRACES_EXPORTER=none
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://127.0.0.1:4318/v1/metrics
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://127.0.0.1:4318/v1/logs
export OTEL_METRIC_EXPORT_INTERVAL=5000
export OTEL_LOG_USER_PROMPTS=0
export OTEL_LOG_ASSISTANT_RESPONSES=0
export OTEL_LOG_TOOL_DETAILS=0
export OTEL_LOG_TOOL_CONTENT=0
export OTEL_LOG_RAW_API_BODIES=0
export OTEL_LOG_MANAGED_SETTINGS=0
export OTEL_METRICS_INCLUDE_SESSION_ID=false
export OTEL_METRICS_INCLUDE_ACCOUNT_UUID=false
export OTEL_METRICS_INCLUDE_REPOSITORY=false
export OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false
export OTEL_RESOURCE_INCLUDE_HOST=0
Même avec ces choix, des attributs comme l’adresse email, l’organisation, un identifiant d’installation ou des caractéristiques du terminal peuvent encore être présents selon l’authentification et la version. Le Collector les reçoit en mémoire, même si basic ne les affiche pas. Utilisez des données d’essai pour cette étape. La télémétrie opérationnelle propre à Anthropic est distincte de cet export OTLP ; ces variables ne prétendent pas la désactiver.
5. Tester les routes avant de démarrer un agent
Dans un deuxième terminal du même serveur, envoyez uniquement ces données synthétiques. La première requête vérifie /v1/logs, la seconde /v1/metrics. Les sondes utilisent la date GNU du serveur pour leur horodatage. Aucun compte de fournisseur n’est nécessaire pour ce test de transport.
otel_demo_ts="$(date +%s%N)"
curl --max-time 5 -fsS -w '\nHTTP %{http_code}\n' \
-H 'Content-Type: application/json' --data @- \
http://127.0.0.1:4318/v1/logs <<EOF
{"resourceLogs":[{"scopeLogs":[{"logRecords":[{"timeUnixNano":"$otel_demo_ts","severityNumber":9,"body":{"stringValue":"atelier.sonde"}}]}]}]}
EOF
otel_demo_ts="$(date +%s%N)"
curl --max-time 5 -fsS -w '\nHTTP %{http_code}\n' \
-H 'Content-Type: application/json' --data @- \
http://127.0.0.1:4318/v1/metrics <<EOF
{"resourceMetrics":[{"scopeMetrics":[{"metrics":[{"name":"atelier.jauge","gauge":{"dataPoints":[{"asInt":"1","timeUnixNano":"$otel_demo_ts"}]}}]}]}]}
EOF
Attendez un statut HTTP 200 et des résumés de lots dans le premier terminal. En cas de refus de connexion, vérifiez l’écoute. Pour une erreur 404, contrôlez le chemin. Pour une erreur 400, vérifiez le format de la requête. Passez ensuite à l’essai des clients pour vérifier leurs exporteurs.
Lorsque vous lancez ensuite manuellement une session d’essai, comparez les arrivées avant et après, attendez l’intervalle d’export puis fermez proprement la session. Pour explorer les valeurs au-delà du résumé, raccordez un backend de métriques sur le serveur de test et définissez sa durée de conservation.
6. Garder les logs comme option de laboratoire
Pour un essai de journalisation, remplacez exporter = "none" chez Codex par le réglage ci-dessous. Chez Claude Code, passez OTEL_LOGS_EXPORTER à otlp. Faites-le seulement dans un nouveau test fictif, puis revenez au réglage initial.
exporter = { otlp-http = { endpoint = "http://127.0.0.1:4318/v1/logs", protocol = "binary" } }
Les arguments d’outils peuvent figurer dans les journaux même lorsque le texte des prompts est masqué. Chez Codex, le réglage tool_result.max_bytes limite la sortie de l’outil incluse dans les journaux. Chez Claude, les options de corps API et de contenu d’outils ouvrent d’autres chemins de collecte. Gardez ces options désactivées pour cet exercice.
Arrêtez le Collector avec Ctrl+C et fermez le terminal contenant les variables d’essai. Les étapes s’exécutent à la demande sur le serveur d’essai. La configuration s’appuie sur la documentation officielle. Les étapes de réception vous permettent de valider votre propre environnement.