Telemetrie-Datenebene

Ongrid-Edges sprechen mit dem Manager über zwei physische Pfade:

Steuerungsebene — der geminio-Tunnel (ADR-001 / ADR-007). Verwendet für Edge-Lifecycle, RPC, Heartbeats, Alarm-Events und Metrik-Push (push_prom_samples).
Telemetrie-Datenebene — direkter ausgehender HTTPS-POST von der Edge zu den öffentlichen Ingest-Endpunkten des Managers. Verwendet für Logs (Loki-API) und Traces (OTLP).

Diese Seite erklärt die Aufteilung, das Authentifizierungsmodell und den Migrationsauslöser für Metriken.

Diese Seite ist die kompakte Referenz. Das vollständige Entscheidungsdokument ist ADR-014 im Quellbaum.

Die Aufteilung

Ebene	Kanal	Trägt
Steuerungsebene	geminio-Tunnel (bestehende ADR-001)	Edge-Lifecycle, RPCs, Heartbeats, Alarm-Events, Metrik-Push (vorerst)
Telemetrie-Datenebene	edge → manager öffentliches HTTPS, unabhängige ausgehende Verbindungen	Logs (ADR-012), Traces (ADR-013)

Beide Ebenen sind ausgehend von der Edge — der Agent wählt den Manager. Keine eingehenden Ports auf der Edge.

Warum aufteilen?

Der geminio-Tunnel wurde als Steuerungs-RPC-Bus entworfen. Er multiplext latenzarme RPC-Aufrufe innerhalb einer persistenten Verbindung. Metrik-Push war eine „Mitfahrgelegenheit", die in ADR-009 hinzugefügt wurde, weil das Metrikvolumen klein ist (ein paar KB/s pro Edge) und der Tunnel freie Kapazität hatte.

Logs und Traces sind nicht klein.

Signal	Pro-Edge-Steady-State	Pro-Edge-Spitze
Metrik	ein paar KB/s	~10 KB/s
Log	zehntausende KB/s	1–10 MB/s
Trace	hängt von der Sample-Rate ab	vergleichbar mit Log

100 Edges × 1 MB/s = 100 MB/s anhaltende Ingress am Manager. Der Tunnel war dafür nicht ausgelegt. Logs und Traces darüber zu zwingen, schlägt zwei Probleme an:

Manager-CPU schmilzt. Tunnel-Frame-Encoding/-Decoding + Weiterleitung an die Downstream-Stores findet im Go-Prozess statt. nginx + Downstream-Store direkt ist um ein Vielfaches günstiger.
HOL-Blocking. Hochdurchsatz-Byte-Streams konkurrieren mit Steuerungs-RPCs auf dem Mux. Operatoren erleben sekundenlange Jitter bei der Frage „Was ist mit Edge 42 los?".

Tunnel ist Steuerungsebene. Datenebene ist Datenebene. Das Vermischen war ein Notbehelf unter NAT-Einschränkungen; die Aufteilung macht die Grenze explizit.

Architektur

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.                   │
   └──────────────┘                    └──────────────────────────────┘

Der Agent verwendet eine TLS-Verbindung pro Plugin (promtail, otelcol-contrib). Sie sind alle ausgehend von der Edge zu ONGRID_PUBLIC_URL.

Authentifizierung

Eine Vertrauenswurzel, zwei Pfade.

Das Access-Key/Secret-Key-Paar der Edge authentifiziert den Tunnel über die Session-Credentials von geminio. Dasselbe Credential-Paar wird gegen einen Bearer-Token getauscht, der bei jedem Daten-Ebenen-HTTPS-POST verwendet wird. Die auth_request-Direktive von nginx ruft den Manager unter /internal/auth/dataplane-verify zurück, um den Token zu validieren; bei 200 wird die Anfrage an Loki oder Tempo geproxyt. Bei 401/403 sieht die Edge einen HTTP-Fehler und macht Backoff.

Das bedeutet:

Das Rotieren des secret_key der Edge invalidiert beide Ebenen gleichzeitig.
Es gibt keinen zweiten Secrets-Store, kein per-Plugin-Credential, keine separate ACL.
Der Manager besitzt die Auth — Loki und Tempo sehen die Edge-Identität nie direkt.

Der Bearer-Token ist kurzlebig. Der Agent erneuert ihn transparent über den Tunnel; eine Edge, deren Tunnel über einen längeren Zeitraum unten ist, sieht, wie Daten-Ebenen-POSTs nach Token-Ablauf zu 401 werden, was eine Tunnel-Reconnect-erzwingt.

NAT-Kompatibilität

Ausgehendes HTTPS zum öffentlichen Port des Managers ist die gleiche Netzwerkklasse wie der ausgehende Tunnel — beide entstehen aus der Edge zu einem einzigen Ziel-Port-Bereich (443 für Daten, 40012 für Tunnel). Beide passieren gewöhnliche Corporate-Egress-Firewalls. Keine besonderen Ausnahmen, keine eingehenden Regeln.

Für NAT-only-Edges, die nur eine ausgehende Verbindung öffnen können, hat geminio einen Raw-Stream-Fallback (zstd-komprimierte Log-Payloads, begrenzter Puffer, Drop-Old bei Overflow). Das ist ein Notausgang, nicht der Standard — wir mussten ihn bei keinem Kunden bisher ausliefern.

Was ist mit Metriken?

push_prom_samples ist heute noch auf dem Tunnel.

Warum wir es auf dem Tunnel behielten
Metrikvolumen pro Edge ist weit unter der Sättigung.
Der bestehende Pfad funktioniert; Migrationskosten überwiegen den aktuellen Nutzen.
`push_prom_samples` wird in jedem Release exerziert; es anzufassen ist riskant.

Wir werden Metriken auf die Datenebene (Prometheus remote_write direkt an https://<manager>/api/v1/write) verschieben, wenn irgendeines der folgenden gilt:

Tunnel-CPU eines einzelnen Managers anhaltend > 60 %.
Metrik-Push-Rate einer einzelnen Edge anhaltend > 100 KB/s (meist Runaway-Kardinalität — fixen Sie das zuerst; wenn es danach bleibt, migrieren).
Steuerungs-RPC-P95-Latenz degradiert > 500 ms unter Metrik-Stream-Druck.

Der Prometheus-remote_write-Client ist bereits in node_exporter, und das Metrik-Plugin der Edge kann per Env umverdrahtet werden. Der obige Trigger setzt nur die Priorität.

Edge-Implementierung

Auf der Platte routet der Agent jeden Telemetrie-Sender durch internal/edgeagent/dataplane/. Dieses Paket zentralisiert:

Token-Wiederverwendung aus der Tunnel-Session-Credential.
Dual-Destination-Routing (Tunnel für Steuerung, HTTPS für Daten).
Retry + exponentielles Backoff mit Jitter, gedeckelt bei 1 Minute.
Lokale begrenzte Queue (in-memory; der Agent spoolt nicht auf die Platte).

Jedes Plugin (promtail, otelcol-contrib, künftige) konsumiert dieses Paket — es gibt keine per-Plugin-Retry-/Auth-Logik. Das hält ongrid-edge als ein einzelnes Binary plus vier Subprozesse; kein per-Plugin-Sidecar, keine per-Plugin-systemd-Unit.

Was Sie tunen

Variable	Wo	Wirkung
`ONGRID_PUBLIC_URL`	Manager	Die URL, die Edges als Daten-Ebenen-Wurzel ausgehändigt wird. Erforderlich, damit die Datenebene funktioniert.
`ONGRID_LOG_QUERY_URL`	Manager	Lesepfad — Manager → Loki für die Logs-Seite. Unabhängig vom Edge-Push.
`ONGRID_TRACE_QUERY_URL`	Manager	Lesepfad — Manager → Tempo für die Traces-Seite.
`ONGRID_EDGE_PLUGIN_BIN_DIR`	Edge	Wo die Plugin-Binaries liegen (promtail, otelcol-contrib).
`ONGRID_EDGE_PLUGIN_WORK_DIR`	Edge	Per-Plugin-Runtime-Dirs (Configs, PID, Queue-Spool).

ONGRID_PUBLIC_URL ist die einzelne wichtigste Produktionseinstellung auf der Manager-Seite. Leer deaktiviert die Datenebene komplett — Edges verbinden sich über den Tunnel, der Agent bootet, aber Logs und Traces werden nie ausgeliefert.

Siehe auch

Architektur — vollständiges Systemdiagramm.
Fähigkeiten → Logs — Operator-Tour der Logs-Ebene.
Fähigkeiten → Traces — Operator-Tour der Traces-Ebene.
Umgebungsvariablen — die Stellknöpfe, die all dies verdrahten.

Telemetrie-Datenebene ​

Die Aufteilung ​

Warum aufteilen? ​

Architektur ​

Authentifizierung ​

NAT-Kompatibilität ​

Was ist mit Metriken? ​

Edge-Implementierung ​

Was Sie tunen ​

Siehe auch ​