Monitoramento

O Ongrid distribui um pipeline de monitoramento funcional de fábrica e é projetado para se dobrar ao seu existente quando você já tem um.

O data plane

edge:
  hostmetrics, procmetrics, node-exporter  ─┐
                                            │  remote_write (HTTPS direct)
                                            ▼
                                       ┌─────────┐
                                       │  Prom   │  (default: bundled)
                                       └────┬────┘
                                            │ query_range / instant
                                            ▼
                                  ┌──────────────────────┐
                                  │  manager:            │
                                  │   - alert evaluator  │
                                  │   - query_promql     │
                                  │   - /api/grafana     │
                                  └──────────────────────┘

O padrão é o Prometheus bundled rodando no docker-compose em prometheus:9090. Edges fazem push direto a ele por HTTPS — sem scrape, sem descoberta de node. Esse é o split data-plane / control-plane do ADR-014: o tunnel geminio carrega controle, a telemetria vai direto.

Por que direto, não pelo tunnel

Em cardinalidade ≥ 5 k séries/seg em uma instalação de 50 hosts, multiplexar remote_write pelo tunnel geminio engasgou. O remote_write direto remove o manager do hot path e deixa o write- ahead-log do próprio Prom lidar com o buffer de ingestão. O trade-off é mais um endpoint HTTPS a expor; veja Instalação do servidor para o snippet de reverse-proxy do nginx.

Prom built-in vs externo

Ambos os modos são first-class.

Built-in (padrão)

docker compose up sobe prometheus:v2.55 com --web.enable-remote-write-receiver. Armazenamento é um volume nomeado ongrid_prom_data. Retenção padrão é 15d — tune via PROMETHEUS_RETENTION no .env.

O manager fala com ele em http://prometheus:9090 via o env ONGRID_PROM_QUERY_URL. Sem configuração adicional necessária.

Externo

Aponte ONGRID_PROM_QUERY_URL para seu próprio endpoint de query de Prom / VictoriaMetrics / Thanos. Edges continuam fazendo remote_write — aponte-os para sua URL de ingest setando o remote_write_url por edge na config do plugin de Edge (internal/manager/biz/edge/plugin_config.go).

O Prom embarcado pode continuar rodando como um Prom de "self-observability" que só raspa o próprio manager (métricas self-obs do ADR-026 vivem ali). Alertas que precisam das duas metades podem ser definidos duas vezes com match_scope_types diferentes.

O caminho de query

Dois consumidores, um client.

Evaluator de alerta

PipelineEvaluator.evaluatePromQuery roda o Expr de cada rule metric_raw habilitada em um tick. Os próprios operadores de comparação do PromQL (up == 0, cpu_pct > 90) SÃO o predicado — o Prom descarta séries não casantes da resposta, então o evaluator só dispara um incidente por entrada de vetor retornada e colhe o resto no sweep de recovery do próximo tick.

// pipeline.go:269
res, err := e.prom.Query(ctx, rule.Expr, now)
// ...
for _, ent := range entries {
    dedupeKey := fmt.Sprintf("pipeline:%s:%s", rule.RuleKey, labelSetKey(ent.Metric))
    // ... RecordFiring + notify
}

A tool query_promql

O LLM ganha um BaseTool chamado query_promql que recebe uma query instant ou range e retorna o vetor / matriz JSON. A persona investigator a usa como probe primária de métrica; o chat do coordinator a usa sempre que você pergunta "qual o cpu de edge-prod-04 agora?"

Schema vive em query_promql_basetool.go; engine subjacente é internal/pkg/promquery.

Grafana embarcado

O compose distribui Grafana em grafana:3000. O manager o proxia sob /api/grafana/* (auth checada no proxy) para que o MonitorPanel.tsx do SPA possa embarcar iframes com um clique — sem login separado de Grafana.

De fábrica, o manager espelha definições internas de painel de monitor no Grafana via biz/grafana/Service em um tick de sync. Operadores editam painéis no Grafana (o editor rico), o manager os recolhe. A página MonitorEditor no SPA é um read-then-redirect fino que abre o editor de painel do Grafana pré-preenchido com a série relevante.

Credenciais do Grafana

O Grafana bundled vem com admin / admin. Mude antes de expor. Veja Checklist de primeiro boot.

Self-observability

ADR-026 conectou /metrics no manager + 6 alertas baseline (spike de tokens LLM, stall do evaluator de alerta, storm de desconexão de tunnel, lag de audit-log, backlog do investigator, p99 de latência de RCA). Eles são semeados no primeiro boot nas tabelas de rules + dashboard e re-asseridos em cada upgrade.

O Prom bundled raspa o /metrics do manager. No modo Prom externo você precisa adicionar um scrape target em manager:9100 (padrão ONGRID_METRICS_ADDR).

Veja também

• Alertas — os kinds de rule que consultam Prom.
• Traces — o gerador de spanmetrics que alimenta séries traces_spanmetrics_* de volta ao mesmo Prom.
• Logs — o pipeline paralelo para Loki.
• Variáveis de ambiente — cada knob ONGRID_PROM_* e PROMETHEUS_*.