Konzepte

Diese Seite stellt die Substantive vor, die Ongrid verwendet, in Abhängigkeitsreihenfolge. Wenn Sie den Schnellstart absolviert haben, wird Ihnen die konkrete Form bereits vertraut sein; hier geben wir ihr Namen.

Edge

Eine Edge ist ein laufender ongrid-edge-Prozess — einer pro Host. Sie ist die Einheit der Registrierung, Telemetrie und Fernsteuerung.

Jede Edge hat:

• einen serverseitig generierten Access Key (eher öffentlich, identifiziert die Edge) und einen Secret Key (einmal angezeigt, dient zur Authentifizierung des Tunnels),
• eine langlebige ausgehende TCP-Verbindung zum Frontier-Broker auf Port 40012,
• eine Flotte überwachter Plugin-Subprozesse (promtail, node_exporter, process_exporter, otelcol-contrib),
• ein Heartbeat, der alle paar Sekunden tickt — wenn er stoppt, wird die Edge nach ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (Standard 90s) als offline markiert.

Edges sind adressierbar über die ganzzahlige edge_id (verwendet in URLs und in Agent-Tool-Aufrufen) oder über den name (verwendet in der UI und von find_topology_node). Sie können sie über list_edges auflisten, einen Befehl auf einer bestimmten ausführen via bash mit edge_id=N oder eine PromQL-Abfrage auf eine fokussieren via query_promql mit einem Host-Label.

Wichtig: eine Edge ist standardmäßig schreibgeschützt. Die hostseitigen Skills des Agenten sind Inspektion (bash, host_probe_*, query_processes, query_logs_tail, host_read_file) — sie mutieren nicht. Schreibaktionen gehen durch den WebShell-Fluss mit Audit-Logging.

Siehe Edge-Installation und Plattformen / Linux-Edge für die konkreten Bereitstellungspfade.

Device

Ein Device ist ein weicheres Konzept als eine Edge. Während eine Edge 1:1 auf einen ongrid-edge-Prozess abbildet, ist ein Device alles, was Ongrid kennt und an einer Topologie teilnimmt — einschließlich Dienste, virtuelle Hosts, k8s-Pods und externe Endpunkte, die durch SD entdeckt oder manuell importiert wurden.

Aktuell zeigt die UI Devices implizit über die Topologie-Ansicht. Ein Device ist ein Knoten im Topologie-Graphen; Edges, Dienste und entdeckte externe Systeme sind alle Knoten. Die Skills expand_topology und find_topology_node operieren über Devices — die Argumentation zum Wirkungsradius hängt von diesem Graphen ab.

TIP

Wenn Sie bisher nur Edges haben, ist Ihr Topologie-Graph eine einzelne Schicht von Host-Knoten. Sobald Skills wie discover_services und Integrationen mit k8s SD ihn füllen, sehen Sie Dienst-Knoten über den Hosts erscheinen und externe Endpunkte zur Seite.

Alarmregel

Eine Alarmregel ist eine deklarative Spezifikation, die ein Alarm-Ereignis feuert, wenn eine Bedingung auf einem Telemetrie-Stream zutrifft.

Ongrids Regelmodell ist zweidimensional: eine Regel hat eine Art (welcher Datentyp evaluiert wird) und einen Scope (wo evaluiert wird).

Die 14 eingebauten Arten, gruppiert nach Datenebene:

Ebene	Arten
Host-Metriken	host_cpu, host_mem, host_disk, host_load, edge_offline, prom_ingest_fail
Metrik/PromQL	promql_threshold, promql_burn_rate, promql_absence
Logs	log_match, log_volume
Traces	trace_latency, trace_error_rate
Komposit	composite_and (eine beliebige der obigen, UND-verknüpft)

Regeln tragen:

• eine Bedingung in der nativen Abfragesprache der Art,
• eine Schwelle + for-Dauer (wie lange die Bedingung gehalten werden muss, bevor sie feuert),
• eine Severity (critical / warning / info),
• ein Routing — welche Kanäle Benachrichtigungen erhalten, mit optionalem Cooldown.

Die 6 eingebauten Host-Regeln (host_cpu, host_mem, host_disk, host_load, edge_offline, prom_ingest_fail) werden mit vernünftigen Standards aus ONGRID_ALERT_*-Umgebungsvariablen geseedet und können in der UI ein-/ausgeschaltet werden. Benutzerdefinierte Regeln liegen in MySQL und können frei editiert werden.

Siehe Alarme-Fähigkeit; das Regelschema ist unter Alarmregel-Schema in der Referenz-Seitenleiste dokumentiert.

Incident

Ein Incident ist eine übergeordnete Gruppierung von Alarm-Ereignissen, die zur gleichen operativen Geschichte gehören. Während ein Alarm jedes Mal feuert, wenn die Bedingung zutrifft, wird ein Incident einmal erstellt und aktualisiert, wenn verwandte Alarme eintreffen.

Incidents sind die Einheit von:

• Investigation — ein Incident, eine oder mehrere Investigations.
• Paging — Kanal-Routing geschieht zum Zeitpunkt der Incident-Erstellung, nicht pro Alarm.
• Timeline — die Incident-Detailseite ist die chronologische Aufzeichnung jedes Alarm-Ereignisses, jeder Agent-Aktion und jeder Operator-Notiz, die an dieselbe Geschichte gebunden sind.
• Schließung — Incidents durchlaufen open → investigating → mitigated → resolved (oder false_positive). Statusänderungen werden im Audit-Log erfasst.

Die Gruppierungslogik ist derzeit absichtlich einfach: nach {rule_id, edge_id}-Tupel mit einem 1-Stunden-Aktivitätsfenster. Die Roadmap sieht vor, dies pro Regel konfigurierbar zu machen (group_by).

Investigation

Eine Investigation ist ein strukturierter Agent-Durchlauf, der an einen Incident angehängt ist. Die Ausgabe ist ein Markdown-Investigation-Report — eine geordnete Liste wahrscheinlicher Grundursachen plus Belege.

Eine typische Investigation durchläuft fünf Sub-Agenten:

1. incident-investigator (coordinator) — zerlegt den Incident in Hypothesen.
2. sre specialist — prüft SLO-Burn, kürzliche Deploys, Alarm-Korrelation.
3. compute / disk / network specialists — host-level Probing auf den betroffenen Edges.
4. ops specialist — Wissensbasis-Lookup, Runbook-Abgleich.
5. reviewer (Critic-Loop) — liest den Berichtsentwurf erneut und fragt vor dem Signoff nach fehlenden Belegen.

Jeder Schritt wird in der Reasoning-Timeline in der UI festgehalten — jeder Tool-Aufruf, jedes Modell-Token, jede Sub-Agent-Dispatch. Auditierbarkeit ist der Punkt.

Sie können eine Investigation auch manuell aus einem beliebigen Incident oder aus dem Chat heraus starten („investigate the order-service drop at 14:02"). Die Ausgabe geht an denselben Ort: ein Investigation-Report, der an einen Incident gebunden ist.

Siehe RCA-Fähigkeit; die Persona, die Investigations ausführt, ist unter Incident investigator in der Agents-Seitenleiste dokumentiert.

Kanal

Ein Kanal ist ein konfiguriertes ausgehendes Ziel für Benachrichtigungen. „Kanal" deckt zwei leicht unterschiedliche Formen ab:

• Webhook-Kanäle — Slack Incoming Webhooks, Larksuite (Feishu) Webhooks, DingTalk Webhooks, WeCom Gruppen-Roboter, generischer Webhook. Diese sind einseitig — Ongrid postet eine Karte und das war's.
• IM-Kanäle — Telegram-Bot, Larksuite-App, DingTalk-App, WeCom-App, Slack-App. Diese sind zweiseitig — derselbe Kanal liefert Alarme UND lässt den Benutzer antworten, dem Agenten eine Frage stellen, eine Investigation auslösen.

Jeder Kanal hat:

• einen Namen (frei wählbar), einen Typ (slack / feishu / dingtalk / wecom / webhook / telegram) und Endpunkt-Material (URL + Secret, oder App-Token + Chat-ID, oder Bot-Token + allow-from-Liste…).
• einen Scope — welche Org / welche Rollen hierher geroutete Benachrichtigungen sehen können. Plus eine optionale allow_from-Sender-Allowlist (speziell Telegram), damit zufällige Personen nicht mit Ihrem Bot reden können.
• ein Default-Locale — in welcher Sprache der Agent auf diesem Kanal antwortet, unabhängig vom UI-Locale.

Kanäle sind erstklassig: Alarmregeln referenzieren sie per Name, der Agent kann proaktiv Nachrichten an sie senden, und Sie können einen Kanal an mehrere Regeln verdrahten, ohne Webhook-URLs erneut einzufügen.

Siehe Kanäle-Übersicht.

IM-Kanal (zweiseitig)

Ein Subtyp von „Kanal", der eine separate Erwähnung wert ist. Ein IM-Kanal macht aus einer Chat-Oberfläche (Telegram, Larksuite, DingTalk, WeCom, Slack) eine vollständige Agent-Schnittstelle.

Was zweiseitig konkret bedeutet:

• Der Agent kann posten — Alarme, Investigation-Reports, geplante Digests.
• Der Benutzer kann antworten — Fragen („why was the disk full?"), Befehle („/list edges"), Follow-ups („investigate that").
• Jede Nachricht ist an denselben user_agent und org gebunden wie die Web-UI-Sitzung — gleiche RBAC, gleiches Audit-Log, gleiche Skill-Registry.
• Eine sender_allowlist (Telegram) oder ein App-Permission-Gate (die anderen) entscheidet, wer in einer Gruppe mit dem Bot reden darf.

Per-Kanal-Locale zählt hier. Das benutzerorientierte UI-Locale mag Englisch sein; eine Telegram-Gruppe will vielleicht trotzdem Antworten auf Chinesisch; das setzen Sie pro Kanal.

Siehe Kanäle / Telegram für das flexibelste Beispiel.

Persona / Agent

Eine Persona ist eine konfigurierbare Agent-Identität — eine YAML/JSON-Deklaration von:

• welches Modell der Agent bevorzugt (mit Site-Default als Fallback),
• welche Skills erlaubt sind (Skills tragen einen scope: host, manager, org, und eine class: safe, payload_read, payload_write — siehe RBAC),
• ein System-Prompt in der Stimme des Agenten,
• optionale Sub-Agent-Deklarationen (eine coordinator-Persona kann specialist-Personas spawnen).

Ongrid liefert mehrere Personas von Haus aus:

• coordinator — der Standard; zerlegt Benutzerfragen, routet zu specialists oder ruft Skills direkt auf.
• incident-investigator — Incident-Modus-coordinator; durchläuft die Topologie, korreliert Signale, entwirft einen Bericht.
• sre, network, compute, disk, ops — specialists, die von den coordinators aufgerufen werden.
• reviewer — Critic-Loop für den Entwurf des incident-investigator.

Sie können eigene verfassen. Das Persona-Format ist unter Agent-Persona-Format in der Referenz-Seitenleiste dokumentiert. Benutzerdefinierte Personas landen in MySQL; sie werden beim nächsten Agent-Lauf aufgenommen.

Skill

Ein Skill ist ein aufrufbares Werkzeug, das der Agent aufrufen kann. Jeder Skill deklariert:

• einen Namen (z. B. query_promql, bash, expand_topology),
• ein JSON-Schema für Argumente und Ergebnis,
• einen Scope — host (läuft auf einer bestimmten Edge über den Tunnel), manager (läuft im Manager-Prozess) oder org (Cross-Edge-Manager-Skill),
• eine Class — safe, payload_read, payload_write. Read-only-Classes sind uneingeschränkt; Write-Classes gehen durch Approval.
• ein optionales Aktivierungs-Schlüsselwort — wenn gesetzt, bleibt der Skill aus dem Prompt heraus, es sei denn, die Frage des Benutzers erwähnt ein Schlüsselwort. Dies ist der Toolbag-Deferral-Mechanismus, der die Skill-Registry davor bewahrt, das Kontextfenster des Modells zu sprengen.

Skills werden in einer Registry gespeichert. Der Agent-Kernel (standardmäßig graph-Kernel) löst auf, welche Skills für den aktuellen Turn sichtbar sind, basierend auf scope, RBAC und Aktivierungs-Schlüsselwörtern. Etwa 30 Skills werden mitgeliefert (bash, host_probe_*, query_promql, query_logs, query_traceql, expand_topology, find_topology_node, read_repo, search_knowledge, web_search, …).

Siehe Skills-Fähigkeit; das Manifest-Format ist unter Skill-Manifest in der Referenz-Seitenleiste dokumentiert. Benutzerdefinierte Skills können aus ONGRID_SKILLS_EXTERNAL_DIRS geladen werden.

Wissensbasis

Eine Wissensbasis ist eine Sammlung von Organisationsdokumenten, die der Agent über search_knowledge durchsuchen kann. Dokumente werden einmal eingebettet und in Qdrant gespeichert; das Retrieval ist hybrid (Vektor + BM25).

Quellen sind geschichtet:

• vault — die eingebaute, schreibgeschützte Wissensbasis, die mit Ongrid gebündelt wird. Etwa 100 Markdown-Playbooks, die Netzwerkdiagnose, Linux-Interna, Prometheus- / Loki- / Tempo-Rezepte und gängige Incident-Muster abdecken. Der Vault synchronisiert sich auf Anforderung aus dem öffentlichen ongridio/vault-Repo.
• upload — Markdown-, TXT-, PDF-, DOCX-Dateien, die von einem Org-Admin hochgeladen werden. Geht durch docextract und landet im Upload-Baum.
• manual — direkt im UI-Editor verfasste Einträge.
• repo — ganze Git-Repositories, synchronisiert mit schreibgeschützten SSH-Keys (ADR-023). Nützlich für das Ingesten Ihres eigenen Runbook-Repos.

Der Agent ruft search_knowledge(query, k=N) und erhält geordnete Chunks mit Metadaten zurück. Embeddings werden standardmäßig von einem offline ONNX-gebündelten BGE-Modell berechnet (fast-bge-small-zh-v1.5); Sie können einen gehosteten Embedder (OpenAI, Zhipu, GLM…) über Settings einbinden.

Siehe Wissensbasis-Fähigkeit.

Alles zusammen

Eine typische Betriebsschleife:

  edge ─▶ telemetry ─▶ alert rule ─▶ alert event ─▶ incident
                                                       │
                                              ┌────────┴────────┐
                                              ▼                 ▼
                                       investigation        channel
                                       (agent + skills)     (Slack / TG /
                                              │              IM …)
                                              ▼
                                       investigation
                                       report

• Eine Edge liefert Telemetrie.
• Eine Alarmregel evaluiert sie und erzeugt ein Alarm-Ereignis.
• Das Ereignis wird in einen Incident gruppiert (oder an einen offenen angehängt).
• Der Incident routet an Kanäle zur Benachrichtigung.
• Eine Investigation wird automatisch gestartet (oder vom Operator ausgelöst); der Agent verwendet Skills und die Wissensbasis, um einen Bericht zu produzieren.
• Eine Persona entscheidet die Stimme + Tool-Palette, mit der die Investigation läuft.

Die gesamte Pipeline ist beobachtbar: jeder Schritt erscheint in der UI-Timeline, jeder Skill-Aufruf ist im Audit-Log, jede Token-Ausgabe ist im LLM-Budget-Panel.