Exporter OTel pour la télémétrie Cortex (émission OTLP — le dashboard vit hors de Cortex)

[cdeust]

Directive cas-d'école + artifact de clôture du cours 6 du guide d'activation (2026-07-14). Décision d'architecture (user) : l'instrumentation OTel appartient à Cortex (émission), le dashboard N'appartient PAS à Cortex — la consommation/visualisation ops se fait par un collector OTLP + l'outillage standard du déploiement (Grafana/Datadog…), et cortex-viz reste la visualisation produit (brain/graph), pas un dashboard ops.

Périmètre :

1. Brancher un exporter OTLP optionnel sur le sous-système télémétrie existant (mcp_server/core/telemetry.py écrit aujourd'hui ~/.claude/methodology/telemetry.jsonl — conserver ce défaut local-sans-egress, qui est un argument compliance documenté). Activation par variables d'env standard OTel (OTEL_EXPORTER_OTLP_ENDPOINT, service name…), OFF par défaut.
2. Vérifier les conventions contre la doc OTel de Claude Code (code.claude.com) avant de figer les noms de variables/métriques — ne PAS reconstruire de mémoire (l'utilisateur ne dispose pas de la config de référence du cours ; source à retrouver).
3. Métriques candidates (à confronter au scorecard d'activation) : latence par outil (p50/p95, déjà comptée par telemetry.record), taux d'erreur par outil, ratio lectures/écritures, santé du grooming.
4. Livrable annexe hors repo : spec de dashboard 3 métriques (nom/source/baseline saine) pour l'équipe ops du déploiement — dans le pack d'activation, pas dans Cortex.

Réfs : #120 (META cas-d'école), gap « télémétrie OFF par défaut sur chemins tiers » (leçon 3.2 — l'observabilité vient d'OTel/gateway), contrôles opérationnels cours 6 (audit logs 180 j / Compliance API).

[cdeust]

La « supplied OTel reference config » manquante est arrivée via la leçon mesure du guide (2026-07-14) — le point 2 de cette issue est résolu, sources désormais citables :

• Activation développeur : CLAUDE_CODE_ENABLE_TELEMETRY=1 (export console par défaut ; routable vers tout backend OTLP).
• Déploiement org-wide (le chemin enterprise, >50 devs) : bloc managed-settings.json {"telemetry": {"enabled": true, "otlpEndpoint": "https://otel.<backend>"}} — à déployer AVANT l'install des devs, non contournable individuellement.
• Métriques Claude Code exposées : session.count, active_time.total, lines_of_code.count, commit.count, pull_request.count, cost.usage, token.usage.
• Caveat de source : l'Analytics API Anthropic couvre claude.ai (agrégats) — pour Claude Code, les métriques session/coût viennent de l'OTel pipeline ou de l'Admin Console, PAS de l'Analytics API.

Pour l'exporter Cortex (point 1) : s'aligner sur ces conventions de nommage (préfixe cortex.* en miroir : cortex.tool.duration, cortex.tool.calls, cortex.recall.results…) pour que les deux sources coexistent proprement dans le même collector. Vérification finale contre code.claude.com/docs avant implémentation (les noms ci-dessus sortent du matériau de cours, pas de la doc produit).

[cdeust]

Addendum (leçon OTel approfondie) — sémantique à MIROIR pour l'exporter cortex.* : ① master switch distinct (la télémétrie Cortex locale reste toujours-on ; l'EXPORT est l'opt-in) ; ② séparer métriques/événements comme Claude Code (OTEL_METRICS_EXPORTER vs OTEL_LOGS_EXPORTER) ; ③ hiérarchie de vie privée identique : jamais de CONTENU (queries de recall, contenus de mémoires) dans les événements par défaut — compteurs/latences/statuts seulement ; tout contenu exigerait un opt-in explicite séparé, à documenter pour la security review ; ④ attributs d'attribution : réutiliser OTEL_RESOURCE_ATTRIBUTES standard plutôt qu'un mécanisme maison. Protocole : gRPC :4317 défaut, http/json en fallback. Vérif : OTEL_METRIC_EXPORT_INTERVAL court en dev puis retiré.