Data plane de telemetria

Edges do Ongrid falam com o manager por dois caminhos físicos:

Control plane — o tunnel geminio (ADR-001 / ADR-007). Usado para ciclo de vida do edge, RPC, heartbeats, alert events, e push de métrica (push_prom_samples).
Data plane de telemetria — POST HTTPS outbound direto do edge para os endpoints públicos de ingest do manager. Usado para logs (Loki API) e traces (OTLP).

Esta página explica o split, o modelo de autenticação, e o trigger de migração para métricas.

Esta página é a referência concisa. O record de decisão completo é ADR-014 na árvore de source.

O split

Plane	Canal	Carrega
Control plane	tunnel geminio (ADR-001 existente)	ciclo de vida do edge, RPCs, heartbeats, alert events, push de métrica (por enquanto)
Data plane de telemetria	edge → HTTPS público do manager, conexões outbound independentes	logs (ADR-012), traces (ADR-013)

Ambos os planes são outbound do edge — o agent disca para o manager. Sem portas inbound no edge.

Por que separar?

O tunnel geminio foi projetado como um bus de control-RPC. Multiplexa chamadas RPC de baixa latência dentro de uma conexão persistente. Push de métrica foi um "ride grátis" adicionado no ADR-009 porque volume de métrica é pequeno (alguns KB/s por edge) e o tunnel tinha capacidade sobrando.

Logs e traces não são pequenos.

Sinal	Steady state por-edge	Pico por-edge
métrica	alguns KB/s	~10 KB/s
log	dezenas de KB/s	1–10 MB/s
trace	depende da sample rate	comparável a log

100 edges × 1 MB/s = 100 MB/s sustentados de ingresso no manager. O tunnel não foi projetado para isso. Forçar logs e traces por ele bate em dois problemas:

CPU do manager derrete. Encoding/decoding de frame de tunnel + forward para stores downstream acontece no processo Go. nginx + store downstream direto é várias vezes mais barato.
HOL blocking. Streams de byte de alto throughput contendem com RPCs de controle no mux. Operadores experimentam jitter de nível-segundo ao perguntar "o que há de errado com edge 42?".

Tunnel é control plane. Data plane é data plane. Misturá-los foi expediente sob constraints de NAT; o split torna o limite explícito.

Arquitetura

text

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

O agent usa uma conexão TLS por plugin (promtail, otelcol-contrib). Todas são outbound do edge para ONGRID_PUBLIC_URL.

Autenticação

Uma raiz de trust, dois caminhos.

O par access-key/secret-key do edge autentica o tunnel via credenciais de sessão geminio. O mesmo par de credencial é trocado por um token Bearer usado em cada POST HTTPS do data-plane. A diretiva auth_request do nginx faz call-back ao manager em /internal/auth/dataplane-verify para validar o token; em 200, a request é proxiada para Loki ou Tempo. Em 401/403, o edge vê um erro HTTP e faz backoff.

Isso significa:

Rotacionar o secret_key do edge invalida ambos os planes simultaneamente.
Não há um segundo store de secrets, sem credencial por-plugin, sem ACL separada.
O manager é dono da auth — Loki e Tempo nunca veem identidade de edge diretamente.

O token Bearer é de curta vida. O agent o refresha transparentemente pelo tunnel; um edge cujo tunnel está fora por um período extenso vai ver POSTs do data-plane começarem a dar 401 uma vez que o token expira, o que força um reconnect do tunnel.

Compatibilidade com NAT

HTTPS outbound para a porta pública do manager é a mesma classe de rede que o tunnel outbound — ambos são originados do edge para um único range de porta de destino (443 para dados, 40012 para tunnel). Ambos passam por firewalls comuns de egress corporativo. Sem exceções especiais, sem regras inbound.

Para edges NAT-only que só podem abrir uma conexão outbound, o geminio tem um fallback de raw-stream (payloads de log comprimidos com zstd, buffer limitado, drop-old em overflow). Esse é um escape hatch, não o padrão — não tivemos de distribuir para um cliente ainda.

E sobre métricas?

push_prom_samples ainda está no tunnel hoje.

Por que mantivemos no tunnel
Volume de métrica por edge está bem abaixo de saturação.
O caminho existente funciona; custo de migração supera benefício atual.
`push_prom_samples` é exercitado em cada release; mexer nele é arriscado.

Vamos mover métricas para o data plane (Prometheus remote_write direto para https://<manager>/api/v1/write) quando qualquer um dos seguintes valer:

CPU de tunnel de um único manager sustentada > 60%.
Taxa de push de métrica de um único edge sustentada > 100 KB/s (quase sempre significa cardinalidade descontrolada — conserte isso primeiro; se persistir depois, migre).
Latência P95 de RPC de controle degrada > 500ms sob pressão de stream de métrica.

O client Prometheus remote_write já está no node_exporter e o plugin de métrica do edge pode ser re-apontado via env. O trigger acima só define a prioridade.

Implementação no edge

Em disco, o agent distribui cada sender de telemetria por internal/edgeagent/dataplane/. Esse pacote centraliza:

Reaproveitamento de token da credencial de sessão do tunnel.
Roteamento dual-destination (tunnel para controle, HTTPS para dados).
Retry + backoff exponencial com jitter, limitado a 1 minuto.
Fila local limitada (in-memory; o agent não faz spool em disco).

Cada plugin (promtail, otelcol-contrib, futuros) consome esse pacote — não há lógica de retry / auth por-plugin. Isso mantém ongrid-edge como um único binário mais quatro subprocessos; sem sidecar por-plugin, sem unit systemd por-plugin.

O que você tuna

Variável	Onde	Efeito
`ONGRID_PUBLIC_URL`	manager	A URL passada aos edges como raiz do data-plane. Obrigatória para o data plane funcionar.
`ONGRID_LOG_QUERY_URL`	manager	Caminho de leitura — manager → Loki para a página Logs. Independente do push do edge.
`ONGRID_TRACE_QUERY_URL`	manager	Caminho de leitura — manager → Tempo para a página Traces.
`ONGRID_EDGE_PLUGIN_BIN_DIR`	edge	Onde os binários de plugin vivem (promtail, otelcol-contrib).
`ONGRID_EDGE_PLUGIN_WORK_DIR`	edge	Dirs de runtime por-plugin (configs, PID, queue spool).

ONGRID_PUBLIC_URL é o setting de produção mais importante no lado do manager. Vazio desabilita o data plane inteiramente — edges conectam pelo tunnel, o agent boota, mas logs e traces nunca enviam.

Veja também

Arquitetura — diagrama de sistema completo.
Capacidades → Logs — tour do operador no plane de logs.
Capacidades → Traces — tour do operador no plane de traces.
Variáveis de ambiente — os knobs que conectam tudo isso.

Data plane de telemetria ​

O split ​

Por que separar? ​

Arquitetura ​

Autenticação ​

Compatibilidade com NAT ​

E sobre métricas? ​

Implementação no edge ​

O que você tuna ​

Veja também ​