Plan de données de télémétrie

Les edges Ongrid parlent au manager sur deux chemins physiques :

Plan de contrôle — le tunnel geminio (ADR-001 / ADR-007). Utilisé pour le cycle de vie de l'edge, RPC, heartbeats, événements d'alerte, et push de métriques (push_prom_samples).
Plan de données de télémétrie — POST HTTPS sortant direct de l'edge vers les endpoints d'ingest publics du manager. Utilisé pour les logs (API Loki) et traces (OTLP).

Cette page explique le découpage, le modèle d'authentification et le déclencheur de migration pour les métriques.

Cette page est la référence concise. L'enregistrement de décision complet est ADR-014 dans l'arbre source.

Le découpage

Plan	Canal	Porte
Plan de contrôle	tunnel geminio (ADR-001 existant)	cycle de vie d'edge, RPCs, heartbeats, événements d'alerte, push de métriques (pour l'instant)
Plan de données de télémétrie	edge → HTTPS public du manager, connexions sortantes indépendantes	logs (ADR-012), traces (ADR-013)

Les deux plans sont sortants de l'edge — l'agent compose le manager. Pas de ports entrants sur l'edge.

Pourquoi découper ?

Le tunnel geminio a été conçu comme bus de RPC de contrôle. Il multiplexe les appels RPC à basse latence à l'intérieur d'une connexion persistante. Le push de métriques était un « ride gratuit » ajouté dans ADR-009 parce que le volume de métriques est petit (quelques Ko/s par edge) et le tunnel avait de la capacité de réserve.

Les logs et traces ne sont pas petits.

Signal	État stable par edge	Pic par edge
metric	quelques Ko/s	~10 Ko/s
log	dizaines de Ko/s	1–10 Mo/s
trace	dépend du taux d'échantillonnage	comparable au log

100 edges × 1 Mo/s = 100 Mo/s d'ingress soutenu au manager. Le tunnel n'a pas été conçu pour ça. Forcer les logs et traces dessus touche deux problèmes :

Le CPU du manager fond. L'encodage/décodage de frame tunnel + forwarding vers les stores en aval arrivent dans le processus Go. nginx + store en aval directement est plusieurs fois moins cher.
Blocage HOL. Les streams d'octets à haut débit contendent avec les RPCs de contrôle sur le mux. Les opérateurs expérimentent du jitter au niveau de la seconde en demandant « quel est le problème avec l'edge 42 ? ».

Tunnel est plan de contrôle. Plan de données est plan de données. Les mélanger était un expédient sous contraintes NAT ; le découpage rend la frontière explicite.

Architecture

text

                                      ┌──────────────────────────────┐
   ┌──────────────┐                    │           manager            │
   │ ongrid-edge  │                    │                              │
   │              │                    │  nginx :443  ──► /api/* ───► ongrid (manager)
   │  ┌─────────┐ │   geminio tunnel   │                              │
   │  │  agent  │ ├────► :40012 ──────►│  frontier (geminio broker) ──┤
   │  └─────────┘ │   (control plane)  │                              │
   │              │                    │  nginx :443  ──► /loki/* ───► loki      ← data plane
   │  ┌─────────┐ │                    │              ──► /v1/traces ─► tempo    ← data plane
   │  │promtail │ ├────► :443 ────────►│              ──► /api/v1/write─► prom (today)
   │  └─────────┘ │   (data plane)     │                              │
   │              │                    │  edgeauth verifies the token │
   │  ┌─────────┐ │                    │  via /internal/auth/         │
   │  │otelcol  │ ├────► :443 ────────►│  dataplane-verify before     │
   │  └─────────┘ │   (data plane)     │  proxying.                   │
   └──────────────┘                    └──────────────────────────────┘

L'agent utilise une connexion TLS par plugin (promtail, otelcol-contrib). Elles sont toutes sortantes de l'edge vers ONGRID_PUBLIC_URL.

Authentification

Une racine de confiance, deux chemins.

La paire access-key/secret-key de l'edge authentifie le tunnel via les credentials de session de geminio. La même paire de credentials est échangée contre un token Bearer utilisé sur chaque POST HTTPS de plan de données. La directive auth_request de nginx rappelle dans le manager à /internal/auth/dataplane-verify pour valider le token ; sur 200, la requête est proxifiée vers Loki ou Tempo. Sur 401/403, l'edge voit une erreur HTTP et recule.

Ce qui signifie :

Rotater le secret_key de l'edge invalide les deux plans simultanément.
Il n'y a pas de second store de secrets, pas de credential par plugin, pas d'ACL séparée.
Le manager possède l'auth — Loki et Tempo ne voient jamais l'identité de l'edge directement.

Le token Bearer est à courte durée de vie. L'agent le rafraîchit de façon transparente sur le tunnel ; un edge dont le tunnel est down pour une période étendue verra les POSTs de plan de données commencer à faire 401 une fois que le token expire, ce qui force une reconnexion du tunnel.

Compatibilité NAT

HTTPS sortant vers le port public du manager est la même classe réseau que le tunnel sortant — les deux sont originés depuis l'edge vers une plage de port destination unique (443 pour les données, 40012 pour le tunnel). Les deux passent à travers les firewalls d'egress corporate ordinaires. Pas d'exceptions spéciales, pas de règles entrantes.

Pour les edges NAT-only qui ne peuvent ouvrir qu'une connexion sortante, geminio a un fallback raw-stream (payloads de logs compressés zstd, buffer borné, drop-old en overflow). C'est une trappe d'évacuation, pas le défaut — nous n'avons pas eu à le livrer à un client encore.

Et les métriques ?

push_prom_samples est encore sur le tunnel aujourd'hui.

Pourquoi on l'a gardé sur le tunnel
Le volume de métriques par edge est loin sous la saturation.
Le chemin existant marche ; le coût de migration l'emporte sur le bénéfice actuel.
`push_prom_samples` est exercé dans chaque release ; le toucher est risqué.

Nous déplacerons les métriques vers le plan de données (Prometheus remote_write directement vers https://<manager>/api/v1/write) quand l'une des conditions suivantes tient :

CPU de tunnel d'un manager unique soutenu > 60%.
Taux de push de métriques d'un edge unique soutenu > 100 Ko/s (presque toujours signifie cardinalité débordante — corrigez ça d'abord ; si ça persiste, migrez).
Latence P95 de RPC de contrôle se dégrade > 500ms sous pression de stream de métriques.

Le client remote_write Prometheus est déjà dans node_exporter et le plugin de métriques de l'edge peut être re-pointé via env. Le déclencheur ci-dessus pose juste la priorité.

Implémentation edge

Sur disque, l'agent livre chaque sender de télémétrie à travers internal/edgeagent/dataplane/. Ce package centralise :

Réutilisation de token depuis le credential de session du tunnel.
Routing dual-destination (tunnel pour contrôle, HTTPS pour données).
Retry + backoff exponentiel avec jitter, plafonné à 1 minute.
File locale bornée (in-memory ; l'agent ne spool pas sur disque).

Chaque plugin (promtail, otelcol-contrib, futurs) consomme ce package — il n'y a pas de logique retry / auth par plugin. Ça garde ongrid-edge un seul binaire plus quatre sous-processus ; pas de sidecar par plugin, pas d'unit systemd par plugin.

Ce que vous ajustez

Variable	Où	Effet
`ONGRID_PUBLIC_URL`	manager	L'URL donnée aux edges comme racine du plan de données. Requise pour que le plan de données marche.
`ONGRID_LOG_QUERY_URL`	manager	Chemin de lecture — manager → Loki pour la page Logs. Indépendant du push d'edge.
`ONGRID_TRACE_QUERY_URL`	manager	Chemin de lecture — manager → Tempo pour la page Traces.
`ONGRID_EDGE_PLUGIN_BIN_DIR`	edge	Où les binaires de plugin vivent (promtail, otelcol-contrib).
`ONGRID_EDGE_PLUGIN_WORK_DIR`	edge	Dirs runtime par plugin (configs, PID, spool de file).

ONGRID_PUBLIC_URL est le setting de production le plus important côté manager. Vide désactive le plan de données entièrement — les edges se connectent sur le tunnel, l'agent boote, mais les logs et traces ne livrent jamais.

Voir aussi

Architecture — schéma système complet.
Capacités → Logs — tour opérateur du plan de logs.
Capacités → Traces — tour opérateur du plan de traces.
Variables d'environnement — les boutons qui câblent tout ça.

Plan de données de télémétrie ​

Le découpage ​

Pourquoi découper ? ​

Architecture ​

Authentification ​

Compatibilité NAT ​

Et les métriques ? ​

Implémentation edge ​

Ce que vous ajustez ​

Voir aussi ​