Logs

Logs sind die Loki-Hälfte des L1-Stacks. Sie folgen derselben Datenebenenform wie Metriken: Edges pushen direkt zu Loki über HTTPS, der Manager fragt nur ab.

Die Datenebene

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

ADR-015 Plugin-Laufzeit

promtail läuft als Subprozess unter der Plugin-Laufzeit des Edge-Agenten. Der Agent überwacht den Lebenszyklus — Restart bei Crash, Drain bei Shutdown, Logs ins selbe systemd-Journal wie der Agent. Aus Operator-Sicht ist es ein systemd-Dienst, nicht zwei.

Die frühere Alternative („promtail als statisch gelinkte Go-Bibliothek vendoren") wurde abgelehnt, weil jedes Loki-Client-Upgrade ein erneutes Edge-Agent-Release erzwingen würde. Subprozess entkoppelt sie.

Konfiguration

Per-Edge-Promtail-Config wird serverseitig durch biz/edge/plugin_config.go gerendert und beim Plugin-Start durch den Steuertunnel gepusht. Sie konsultiert system_settings.loki.url, sodass eine Admin-URL-Änderung propagiert, ohne den Agenten neu zu bauen.

Default-Tail-Set:

Quelle	Loki-Labels
`/var/log/syslog`, `/var/log/messages`	`job=node-syslog`, `host=<edge-name>`
systemd journald (alle Units)	`job=systemd-journal`, `host=<edge-name>`, `unit=<svc>`

Benutzerdefinierte Tails werden über die /edges/<id>/logs/sources-Seite der SPA hinzugefügt — sie schreiben in denselben system_settings.loki.*-Namespace.

Die Datenebenen-Aufteilung

ADR-014: Telemetrie geht direkt, Steuerung geht durch den Tunnel. Für Logs heißt das:

✅ promtail HTTPS POST → loki:3100/loki/api/v1/push (direkt).
✅ Loki HTTPS GET ← Manager /loki/api/v1/query_range (direkt).
❌ Logs reisen NICHT durch den geminio-Steuertunnel.

Warum: der Tunnel ist ein In-Process-Multiplexer; Log-Bursts durch ihn zu pipen verhungerte die Steuer-RPCs (RCA-Tool-Aufrufe, WebSSH-I/O), wenn Ingest spiked. Die Datenebene herauszulösen behebt das Noisy-Neighbour-Problem und lässt nginx die öffentliche Oberfläche (TLS, Rate-Limiting, Auth) für beide Hälften einheitlich besitzen.

Alarmarten

Zwei log-getriebene Regelarten — beide Phase-B, beide in evaluators_phaseB.go.

`log_match`

Feuert, wenn count_over_time(<stream_selector> |~ <line_filter> [window]) <op> threshold mindestens einen Matrix-Eintrag zurückgibt.

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 ist optional — wenn leer, zählt die Regel jede Zeile im Stream. Die Abfrage wird pro-Tick von compileLogMatchRule in rules.go:733 gebaut.

`log_volume`

Gleiche Engine wie log_match in v1 (Current-Window-Count vs. absoluter Schwellwert). Die ursprüngliche Spec-Semantik „Ratio vs. vorheriges Fenster" ist geparkt — sie braucht zwei LogQL-Abfragen + Go-seitige Division; die absolute Form deckt bereits den häufigen „Logs spiked past N"-Use-Case ab.

Die Spec-Spalte ist ratio_op / ratio_threshold (für Vorwärtskompatibilität behalten); der Compiler mappt diese auf operator / threshold.

Tools

`search_logs` / `query_logql`

Die LLM-orientierte Logsuche. Zwei Registrierungspfade zeigen auf einen Executor:

query_logql — rohes LogQL-Passthrough. Vom Investigator-Worker verwendet, wenn die Persona genau weiß, welchen Stream abzufragen.
search_logs — freundlicherer Wrapper, in den Quick Actions der Chat-UI exponiert, nimmt eine Freitext-Abfrage + einen Dienstnamen.

Schema + Executor in query_logql_basetool.go. Zugrundeliegender Client: internal/pkg/logquery.

Beide ehren die globale ONGRID_LOG_QUERY_URL-Umgebungsvariable (Default http://loki:3100) und erben Auth von derselben nginx-Schicht, die die Edges zum Pushen verwenden.

`host_tail_file`

Skills-seitige Logsonde — läuft auf der Edge, nicht auf dem Manager. Verwenden Sie dies, wenn Sie die Rohdatei brauchen (z. B. /var/log/ongrid-edge.log, das nicht in journald ist), statt der Loki-ingesteten Ansicht. ScopeHost; erfordert eine edge_id. Siehe Skills für das Dispatch-Modell.

Siehe auch

Alarme — log_match / log_volume Lebenszyklus.
Monitoring — die parallele Pipeline für Prom.
Edge-Installation — das logs-Plugin einschalten.
Telemetrie-Datenebene — vollständige ADR-014-Spur.

Logs ​

Die Datenebene ​

Konfiguration ​

Die Datenebenen-Aufteilung ​

Alarmarten ​

log_match ​

log_volume ​

Tools ​

search_logs / query_logql ​

host_tail_file ​

Siehe auch ​