Logs

Logs são a metade Loki da stack L1. Eles seguem o mesmo formato de data-plane que as métricas: edges fazem push direto ao Loki por HTTPS, o manager só consulta.

O data plane

text

edge:
  ongrid-edge agent
    └─ plugin: promtail (subprocess)
        ├─ tails /var/log/syslog, /var/log/messages, journald
        └─ remote write HTTPS → loki:3100
                                     │
                                     ▼ /loki/api/v1/query_range
                              ┌───────────────┐
                              │  manager:     │
                              │   - alert     │
                              │   - LLM tools │
                              └───────────────┘

Plugin runtime ADR-015

promtail roda como sub-processo sob o plugin runtime do edge agent. O agent supervisiona o ciclo de vida — restart em crash, drain no shutdown, log no mesmo journal systemd que o agent. Do ponto de vista do operador é um único serviço systemd, não dois.

A alternativa anterior ("vendorizar promtail como library Go estaticamente linkada") foi rejeitada porque cada upgrade do client Loki forçaria um re-release do edge agent. Subprocess desacopla os dois.

Configuração

Config do promtail por edge é renderizada server-side por biz/edge/plugin_config.go e empurrada para baixo via o tunnel de controle no start do plugin. Ela consulta system_settings.loki.url para que uma mudança de URL pelo admin se propague sem rebuildar o agent.

Conjunto de tails padrão:

Origem	Labels Loki
`/var/log/syslog`, `/var/log/messages`	`job=node-syslog`, `host=<edge-name>`
journald do systemd (todas as units)	`job=systemd-journal`, `host=<edge-name>`, `unit=<svc>`

Tails custom são adicionados pela página /edges/<id>/logs/sources do SPA — escrevem no mesmo namespace system_settings.loki.*.

O split do data plane

ADR-014: telemetria vai direto, controle vai pelo tunnel. Para logs isso significa:

✅ promtail HTTPS POST → loki:3100/loki/api/v1/push (direto).
✅ Loki HTTPS GET ← manager /loki/api/v1/query_range (direto).
❌ Logs NÃO trafegam pelo tunnel de controle geminio.

Por quê: o tunnel é um multiplexer in-process; canalizar bursts de log por ele matava de fome os RPCs de controle (chamadas de tool de RCA, I/O de WebSSH) quando o ingest disparava. Separar o data plane resolve o problema de noisy-neighbor e deixa o nginx ser dono da superfície pública (TLS, rate limiting, auth) para ambas as metades uniformemente.

Categorias de alerta

Duas categorias de rule dirigidas a log — ambas Phase-B, ambas em evaluators_phaseB.go.

`log_match`

Dispara quando count_over_time(<stream_selector> |~ <line_filter> [window]) <op> threshold retorna pelo menos uma entrada de matriz.

json

{
  "kind": "log_match",
  "scope_type": "global",
  "conditions_json": {
    "stream_selector": "{job=\"systemd-journal\",unit=\"nginx.service\"}",
    "line_filter": "(?i)5\\d{2}",
    "window": "5m",
    "operator": ">=",
    "threshold": 50
  }
}

line_filter é opcional — quando vazio, a rule conta cada linha do stream. A query é montada por tick por compileLogMatchRule em rules.go:733.

`log_volume`

Mesma engine de log_match na v1 (contagem da janela atual vs threshold absoluto). A semântica original do spec de "ratio vs janela anterior" está parqueada — precisa de duas queries LogQL + divisão no lado Go; a forma absoluta já cobre o caso de uso comum "logs estouraram além de N".

A coluna de spec é ratio_op / ratio_threshold (mantida para forward compat); o compiler mapeia esses para operator / threshold.

Tools

`search_logs` / `query_logql`

A busca de log voltada ao LLM. Dois caminhos de registro apontam para um único executor:

query_logql — passthrough cru de LogQL. Usado pelo worker investigator quando a persona sabe exatamente em qual stream consultar.
search_logs — wrapper mais amigável exposto nos Quick Actions da UI de chat, pega uma query free-text + um nome de serviço.

Schema + executor em query_logql_basetool.go. Client subjacente: internal/pkg/logquery.

Ambos honram o env global ONGRID_LOG_QUERY_URL (padrão http://loki:3100) e herdam auth da mesma camada nginx que os edges usam para fazer push.

`host_tail_file`

Probe de log do lado skills — roda no edge, não no manager. Use quando você precisa do arquivo cru (ex.: /var/log/ongrid-edge.log não no journald) em vez da visão ingerida pelo Loki. ScopeHost; exige um edge_id. Veja Skills para o modelo de dispatch.

Veja também

Alertas — ciclo de vida de log_match / log_volume.
Monitoramento — o pipeline paralelo para Prom.
Instalação do edge — ligando o plugin logs.
Data plane de telemetria — trace completo do ADR-014.

Logs ​

O data plane ​

Configuração ​

O split do data plane ​

Categorias de alerta ​

log_match ​

log_volume ​

Tools ​

search_logs / query_logql ​

host_tail_file ​

Veja também ​