Concepts

Cette page présente les noms qu'Ongrid utilise, dans l'ordre de dépendance. Si vous avez fait le Démarrage rapide la forme concrète vous sera déjà familière ; ici on pose des noms dessus.

Edge

Un edge est un processus ongrid-edge en marche — un par host. C'est l'unité d'enrôlement, de télémétrie et de contrôle distant.

Chaque edge a :

• une clé d'accès générée serveur (publique-ish, identifie l'edge) et une clé secrète (montrée une fois, utilisée pour authentifier le tunnel),
• une connexion TCP sortante longue durée au broker frontier sur le port 40012,
• une flotte de sous-processus plugin supervisés (promtail, node_exporter, process_exporter, otelcol-contrib),
• un heartbeat qui tique toutes les quelques secondes — quand il s'arrête, l'edge est marqué offline après ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (défaut 90s).

Les edges sont adressables par edge_id entier (utilisé dans les URLs et dans les appels d'outils de l'agent) ou par name (utilisé dans l'UI et par find_topology_node). Vous pouvez les lister via list_edges, exécuter une commande sur un spécifique via bash avec edge_id=N, ou scoper une requête PromQL à un via query_promql avec un label host.

Important : un edge est lecture seule par défaut. Les skills côté host de l'agent sont d'inspection (bash, host_probe_*, query_processes, query_logs_tail, host_read_file) — ils ne mutent pas. Les actions write passent par le flux WebShell avec audit logging.

Voir installation edge et platforms / linux-edge pour les chemins de déploiement concrets.

Device

Un device est un concept plus souple qu'un edge. Là où un edge mappe 1:1 à un processus ongrid-edge, un device est tout ce qu'Ongrid connaît qui participe à une topologie — y compris services, hosts virtuels, pods k8s et endpoints externes découverts via SD ou importés manuellement.

Pour l'instant, l'UI fait apparaître les devices implicitement via la vue Topologie. Un device est un nœud dans le graphe de topologie ; edges, services et systèmes externes découverts sont tous des nœuds. Les skills expand_topology et find_topology_node opèrent sur les devices — le raisonnement de blast radius dépend de ce graphe.

TIP

Si vous n'avez encore que des edges, votre graphe de topologie est une seule couche de nœuds host. À mesure que des skills comme discover_services et les intégrations avec k8s SD le peuplent, vous verrez apparaître des nœuds service au-dessus des hosts et des endpoints externes sur le côté.

Règle d'alerte

Une règle d'alerte est une spec déclarative qui déclenche un événement d'alerte quand une condition tient sur un stream de télémétrie.

Le modèle de règles d'Ongrid est bidimensionnel : une règle a un kind (quel type de données elle évalue) et un scope (où elle évalue).

Les 14 types intégrés, groupés par plan de données :

Plan	Types
Métriques host	host_cpu, host_mem, host_disk, host_load, edge_offline, prom_ingest_fail
Métrique/PromQL	promql_threshold, promql_burn_rate, promql_absence
Logs	log_match, log_volume
Traces	trace_latency, trace_error_rate
Composite	composite_and (n'importe lequel des ci-dessus, AND-é)

Les règles portent :

• une condition dans le langage de requête natif du type,
• un seuil + durée for (combien de temps la condition doit tenir avant de partir),
• une sévérité (critical / warning / info),
• un routing — quels canaux reçoivent les notifications, avec cooldown optionnel.

Les 6 règles host intégrées (host_cpu, host_mem, host_disk, host_load, edge_offline, prom_ingest_fail) sont seedées avec des défauts sensés depuis les variables d'env ONGRID_ALERT_* et vous pouvez les activer/désactiver depuis l'UI. Les règles personnalisées vivent dans MySQL et peuvent être éditées librement.

Voir capacité alertes ; le schéma de règle est documenté sous Schéma de règle d'alerte dans la sidebar Référence.

Incident

Un incident est un regroupement d'ordre supérieur d'événements d'alerte qui appartiennent à la même histoire opérationnelle. Là où une alerte part chaque fois que la condition tient, un incident est créé une fois et mis à jour à mesure que des alertes connexes arrivent.

Les incidents sont l'unité de :

• investigation — un incident, une ou plusieurs investigations.
• paging — le routage des canaux a lieu à la création d'incident, pas par alerte.
• timeline — la page de détail d'incident est l'enregistrement chronologique de chaque événement d'alerte, action d'agent et note d'opérateur liée à la même histoire.
• clôture — les incidents passent par open → investigating → mitigated → resolved (ou false_positive). Les changements d'état sont audit-loggués.

La logique de regroupement est intentionnellement simple pour l'instant : par tuple {rule_id, edge_id} avec une fenêtre d'activité de 1 heure. La roadmap est de rendre ceci configurable (group_by) par règle.

Investigation

Une investigation est un run d'agent structuré attaché à un incident. La sortie est un rapport d'investigation Markdown — une liste rangée de causes racines probables plus des preuves.

Une investigation typique parcourt cinq sous-agents :

1. incident-investigator (coordinator) — décompose l'incident en hypothèses.
2. specialist sre — vérifie le burn de SLO, les déploiements récents, la corrélation d'alertes.
3. specialists compute / disk / network — sondage au niveau host sur les edges affectés.
4. specialist ops — lookup de base de connaissances, matching de runbook.
5. reviewer (boucle critique) — relit le brouillon de rapport et demande les preuves manquantes avant signoff.

Chaque étape est enregistrée dans la timeline de raisonnement dans l'UI — chaque appel d'outil, chaque token de modèle dépensé, chaque dispatch de sous-agent. L'auditabilité est le sujet.

Vous pouvez aussi lancer une investigation manuellement depuis n'importe quel incident ou depuis le chat (« investigate the order-service drop at 14:02 »). La sortie va au même endroit : un rapport d'investigation lié à un incident.

Voir capacité RCA ; la persona qui exécute les investigations est documentée sous Incident investigator dans la sidebar Agents.

Canal

Un canal est une destination sortante configurée pour les notifications. « Canal » couvre deux formes légèrement différentes :

• Canaux webhook — webhooks entrants Slack, webhooks Larksuite (Feishu), webhooks DingTalk, robots de groupe WeCom, webhook générique. Ceux-ci sont unidirectionnels — Ongrid poste une carte et c'est tout.
• Canaux IM — bot Telegram, app Larksuite, app DingTalk, app WeCom, app Slack. Ceux-ci sont bidirectionnels — le même canal délivre les alertes ET laisse l'utilisateur répondre, poser une question à l'agent, déclencher une investigation.

Chaque canal a :

• un nom (libre), un type (slack / feishu / dingtalk / wecom / webhook / telegram), et le matériel d'endpoint (URL + secret, ou token d'app + chat ID, ou token de bot + liste allow-from…).
• un scope — quelle org / quels rôles peuvent voir les notifications routées ici. Plus une allow_from d'allowlist d'expéditeur optionnelle (Telegram spécifiquement) pour que des gens au hasard ne puissent pas parler à votre bot.
• une locale par défaut — quelle langue l'agent répond sur ce canal, indépendamment de la locale UI.

Les canaux sont de première classe : les règles d'alerte les référencent par nom, l'agent peut leur envoyer des messages proactifs, et vous pouvez câbler un canal à plusieurs règles sans recoller les URLs de webhook.

Voir aperçu des canaux.

Canal IM (bidirectionnel)

Un sous-type de « canal » qui vaut la peine d'être appelé séparément. Un canal IM transforme une surface de chat (Telegram, Larksuite, DingTalk, WeCom, Slack) en une interface d'agent complète.

Ce que bidirectionnel signifie concrètement :

• L'agent peut poster — alertes, rapports d'investigation, digests planifiés.
• L'utilisateur peut répondre — questions (« pourquoi le disque était-il plein ? »), commandes (« /list edges »), follow-ups (« investigate that »).
• Chaque message est lié au même user_agent et org que la session UI Web — même RBAC, même log d'audit, même registre de skills.
• Une sender_allowlist (Telegram) ou gate de permission d'app (les autres) décide qui est autorisé à parler au bot dans un groupe.

La locale par canal importe ici. La locale UI user-facing pourrait être English ; un groupe Telegram peut encore vouloir des réponses en chinois ; vous définissez ça par canal.

Voir channels / telegram pour l'exemple le plus flexible.

Persona / agent

Une persona est une identité d'agent configurable — une déclaration YAML/JSON de :

• quel modèle l'agent préfère (avec le défaut du site en fallback),
• quels skills sont autorisés (les skills portent un scope : host, manager, org, et une class : safe, payload_read, payload_write — voir RBAC),
• un system prompt dans la voix de l'agent,
• des déclarations de sous-agent optionnelles (une persona coordinator peut spawner des personas specialist).

Ongrid livre plusieurs personas out of the box :

• coordinator — le défaut ; décompose les questions utilisateur, route vers les specialists ou exécute des skills directement.
• incident-investigator — coordinator en mode incident ; parcourt la topologie, corrèle les signaux, rédige un rapport.
• sre, network, compute, disk, ops — specialists invoqués par les coordinators.
• reviewer — boucle critique pour le brouillon de incident-investigator.

Vous pouvez créer la vôtre. Le format de persona est documenté sous Format de persona d'agent dans la sidebar Référence. Les personas personnalisées atterrissent dans MySQL ; elles sont prises au prochain run d'agent.

Skill

Un skill est un outil appelable que l'agent peut invoquer. Chaque skill déclare :

• un nom (par ex. query_promql, bash, expand_topology),
• un schéma JSON pour arguments et résultat,
• un scope — host (tourne sur un edge spécifique sur le tunnel), manager (tourne dans le processus manager), ou org (skill manager cross-edge),
• une class — safe, payload_read, payload_write. Les classes lecture seule sont non restreintes ; les classes write passent par approbation.
• un mot-clé d'activation optionnel — si posé, le skill reste hors du prompt sauf si la requête de l'utilisateur mentionne un mot-clé. C'est le mécanisme de toolbag deferral qui empêche le registre de skills d'exploser la fenêtre de contexte du modèle.

Les skills sont stockés dans un registre. Le kernel d'agent (graph kernel par défaut) résout quels skills sont visibles pour le tour courant en fonction du scope, du RBAC et des mots-clés d'activation. Environ 30 skills sont livrés dans la boîte (bash, host_probe_*, query_promql, query_logs, query_traceql, expand_topology, find_topology_node, read_repo, search_knowledge, web_search, …).

Voir capacité skills ; le format de manifeste est documenté sous Manifeste de skill dans la sidebar Référence. Les skills personnalisés peuvent être chargés depuis ONGRID_SKILLS_EXTERNAL_DIRS.

Base de connaissances

Une base de connaissances est une collection de documents d'organisation que l'agent peut chercher via search_knowledge. Les documents sont embeddés une fois et stockés dans Qdrant ; la récupération est hybride (vector + BM25).

Les sources sont en couches :

• vault — la connaissance intégrée, en lecture seule, livrée par Ongrid. Environ 100 playbooks Markdown couvrant diagnostic réseau, internes Linux, recettes Prometheus / Loki / Tempo, patterns d'incident courants. Le vault sync depuis le repo public ongridio/vault à la demande.
• upload — fichiers Markdown, TXT, PDF, DOCX uploadés par un admin d'org. Passe par docextract et atterrit dans l'arbre upload.
• manual — entrées créées directement dans l'éditeur UI.
• repo — dépôts Git entiers synced avec des clés SSH en lecture seule (ADR-023). Utile pour ingérer votre propre repo de runbooks.

L'agent appelle search_knowledge(query, k=N) et récupère des chunks rangés avec métadonnées. Les embeddings sont calculés par un modèle BGE ONNX-bundled offline par défaut (fast-bge-small-zh-v1.5) ; vous pouvez swapper un embedder hosté (OpenAI, Zhipu, GLM…) via Settings.

Voir capacité base de connaissances.

Tout mettre ensemble

Une boucle opérationnelle typique :

  edge ─▶ télémétrie ─▶ règle d'alerte ─▶ événement d'alerte ─▶ incident
                                                                  │
                                                          ┌───────┴────────┐
                                                          ▼                ▼
                                                    investigation        canal
                                                    (agent + skills)     (Slack / TG /
                                                          │              IM …)
                                                          ▼
                                                   rapport
                                                   d'investigation

• Un edge livre la télémétrie.
• Une règle d'alerte l'évalue et produit un événement d'alerte.
• L'événement est groupé en un incident (ou s'attache à un ouvert).
• L'incident route vers des canaux pour notification.
• Une investigation est auto-démarrée (ou déclenchée par opérateur) ; l'agent utilise des skills et la base de connaissances pour produire un rapport.
• Une persona décide de la voix + de la palette d'outils avec laquelle l'investigation tourne.

Tout le pipeline est observable : chaque étape apparaît dans la timeline UI, chaque appel de skill est dans le log d'audit, chaque dépense de token est dans le panel de budget LLM.