Conceptos

Esta página introduce los sustantivos que Ongrid usa, en orden de dependencia. Si has hecho el Quickstart la forma concreta ya te resultará familiar; aquí les ponemos nombre.

Edge

Un edge es un proceso ongrid-edge corriendo — uno por host. Es la unidad de enrollment, telemetría y control remoto.

Cada edge tiene:

• una access key generada por el servidor (semi-pública, identifica el edge) y una secret key (mostrada una sola vez, usada para autenticar el túnel),
• una conexión TCP saliente de larga duración hacia el broker frontier en el puerto 40012,
• una flota de subprocesos de plugin supervisados (promtail, node_exporter, process_exporter, otelcol-contrib),
• un heartbeat que tickea cada pocos segundos — cuando se detiene, el edge se marca como offline tras ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (por defecto 90s).

Los edges son direccionables por edge_id entero (usado en URLs y en llamadas de herramienta del agente) o por name (usado en la UI y por find_topology_node). Puedes listarlos con list_edges, ejecutar un comando en uno específico con bash y edge_id=N, o acotar una query PromQL a uno con query_promql y una label de host.

Importante: un edge es solo lectura por defecto. Los skills del agente del lado del host son inspección (bash, host_probe_*, query_processes, query_logs_tail, host_read_file) — no mutan. Las acciones de escritura pasan por el flujo de WebShell con audit logging.

Ver instalación del edge y platforms / linux-edge para las rutas de despliegue concretas.

Device

Un device es un concepto más blando que un edge. Mientras que un edge mapea 1:1 con un proceso ongrid-edge, un device es cualquier cosa de la que Ongrid tenga conocimiento que participe en una topología — incluyendo servicios, hosts virtuales, pods de k8s y endpoints externos descubiertos por SD o importados manualmente.

Por ahora la UI muestra devices implícitamente a través de la vista Topology. Un device es un nodo en el grafo de topología; edges, servicios y sistemas externos descubiertos son todos nodos. Los skills expand_topology y find_topology_node operan sobre devices — el razonamiento de blast radius depende de este grafo.

TIP

Si por ahora solo tienes edges, tu grafo de topología es una única capa de nodos host. A medida que skills como discover_services e integraciones con SD de k8s lo pueblen, verás aparecer nodos de servicio por encima de los hosts y endpoints externos al lado.

Regla de alerta

Una regla de alerta es una spec declarativa que dispara un evento de alerta cuando una condición se mantiene sobre un stream de telemetría.

El modelo de reglas de Ongrid es bidimensional: una regla tiene un kind (qué tipo de dato evalúa) y un scope (dónde evalúa).

Los 14 kinds integrados, agrupados por data plane:

Plane	Kinds
Métricas de host	host_cpu, host_mem, host_disk, host_load, edge_offline, prom_ingest_fail
Metric/PromQL	promql_threshold, promql_burn_rate, promql_absence
Logs	log_match, log_volume
Trazas	trace_latency, trace_error_rate
Composite	composite_and (cualquiera de los anteriores, AND-ado)

Las reglas llevan:

• una condición en el lenguaje de consulta nativo del kind,
• un threshold + duración for (cuánto debe mantenerse la condición antes de disparar),
• una severity (critical / warning / info),
• un routing — qué canales reciben notificaciones, con cooldown opcional.

Las 6 reglas de host integradas (host_cpu, host_mem, host_disk, host_load, edge_offline, prom_ingest_fail) vienen sembradas con defaults razonables a partir de variables ONGRID_ALERT_* y puedes encenderlas/apagarlas desde la UI. Las reglas customizadas viven en MySQL y se pueden editar libremente.

Ver capacidad de alertas; el esquema de regla está documentado bajo Esquema de reglas de alerta en la barra lateral de Reference.

Incidente

Un incidente es un agrupamiento de orden superior de eventos de alerta que pertenecen a la misma historia operativa. Mientras que una alerta dispara cada vez que la condición se mantiene, un incidente se crea una vez y se actualiza a medida que llegan alertas relacionadas.

Los incidentes son la unidad de:

• investigación — un incidente, una o más investigaciones.
• paging — el routing por canal ocurre al crearse el incidente, no por alerta.
• timeline — la página de detalle del incidente es el registro cronológico de cada evento de alerta, acción del agente y nota de operador atadas a la misma historia.
• cierre — los incidentes se mueven a través de open → investigating → mitigated → resolved (o false_positive). Los cambios de estado quedan en audit log.

La lógica de agrupamiento es intencionadamente simple por ahora: por tupla {rule_id, edge_id} con una ventana de actividad de 1 hora. La roadmap es hacer esto configurable (group_by) por regla.

Investigación

Una investigación es una ejecución estructurada del agente atada a un incidente. La salida es un informe de investigación en Markdown — una lista priorizada de causas raíz probables más evidencia.

Una investigación típica recorre cinco sub-agentes:

1. incident-investigator (coordinator) — descompone el incidente en hipótesis.
2. sre specialist — revisa burn de SLO, deploys recientes, correlación de alertas.
3. compute / disk / network specialists — probing a nivel de host en los edges afectados.
4. ops specialist — búsqueda en base de conocimiento, matching de runbooks.
5. reviewer (critic loop) — relee el informe borrador y pide evidencia faltante antes del signoff.

Cada paso queda registrado en la timeline de razonamiento en la UI — cada llamada de herramienta, cada token del modelo gastado, cada despacho de sub-agente. La auditabilidad es el objetivo.

También puedes lanzar una investigación manualmente desde cualquier incidente o desde el chat ("investiga la caída de order-service a las 14:02"). La salida va al mismo lugar: un informe de investigación atado a un incidente.

Ver capacidad RCA; la persona que ejecuta investigaciones está documentada bajo Incident investigator en la barra lateral de Agents.

Canal

Un canal es un destino de salida configurado para notificaciones. "Canal" cubre dos formas ligeramente diferentes:

• Canales webhook — webhooks entrantes de Slack, webhooks de Larksuite (Feishu), webhooks de DingTalk, robots de grupo de WeCom, webhook genérico. Son unidireccionales — Ongrid publica una tarjeta y ya está.
• Canales IM — bot de Telegram, app de Larksuite, app de DingTalk, app de WeCom, app de Slack. Son bidireccionales — el mismo canal entrega alertas Y permite al usuario responder, preguntar al agente, disparar una investigación.

Cada canal tiene:

• un name (libre), type (slack / feishu / dingtalk / wecom / webhook / telegram) y material de endpoint (URL + secret, o app token + chat ID, o bot token + lista allow-from…).
• un scope — qué organización / qué roles pueden ver las notificaciones enrutadas aquí. Más una lista opcional de remitentes permitidos allow_from (específica de Telegram) para que gente aleatoria no pueda hablar con tu bot.
• un locale por defecto — en qué idioma responde el agente en este canal, independiente del locale de la UI.

Los canales son ciudadanos de primera: las reglas de alerta los referencian por nombre, el agente puede enviarles mensajes proactivos, y puedes cablear un canal a múltiples reglas sin repegar URLs de webhook.

Ver overview de canales.

Canal IM (bidireccional)

Un subtipo de "canal" que vale la pena mencionar aparte. Un canal IM convierte una superficie de chat (Telegram, Larksuite, DingTalk, WeCom, Slack) en una interfaz de agente completa.

Qué significa bidireccional en concreto:

• El agente puede publicar — alertas, informes de investigación, resúmenes programados.
• El usuario puede responder — preguntas ("¿por qué se llenó el disco?"), comandos ("/list edges"), seguimientos ("investiga eso").
• Cada mensaje está vinculado al mismo user_agent y org que la sesión de la UI Web — mismo RBAC, mismo audit log, mismo registry de skills.
• Una sender_allowlist (Telegram) o gate de permisos de app (los otros) decide a quién se le permite hablar con el bot en un grupo.

El locale por canal importa aquí. El locale de UI hacia el usuario podría ser inglés; un grupo de Telegram podría querer respuestas en chino; lo configuras por canal.

Ver channels / telegram para el ejemplo más flexible.

Persona / agent

Una persona es una identidad de agente configurable — una declaración YAML/JSON de:

• qué modelo prefiere el agente (con el default del sitio como fallback),
• qué skills están permitidos (los skills llevan un scope: host, manager, org, y una class: safe, payload_read, payload_write — ver RBAC),
• un system prompt en la voz del agente,
• declaraciones opcionales de sub-agentes (una persona coordinator puede instanciar personas specialist).

Ongrid trae varias personas de fábrica:

• coordinator — la persona por defecto; descompone preguntas de usuario, enruta a specialists o ejecuta skills directamente.
• incident-investigator — coordinator en modo incidente; recorre topología, correlaciona señales, redacta un informe.
• sre, network, compute, disk, ops — specialists invocados por los coordinators.
• reviewer — critic loop para el borrador del incident-investigator.

Puedes crear las tuyas. El formato de persona está documentado bajo Formato de persona de agente en la barra lateral de Reference. Las personas customizadas aterrizan en MySQL; se recogen en la siguiente ejecución del agente.

Skill

Un skill es una herramienta invocable que el agente puede usar. Cada skill declara:

• un name (p. ej. query_promql, bash, expand_topology),
• un JSON schema para argumentos y resultado,
• un scope — host (corre en un edge específico sobre el túnel), manager (corre en el proceso del manager) u org (skill del manager que cruza edges),
• una class — safe, payload_read, payload_write. Las clases read-only son sin restricción; las clases write pasan por aprobación.
• una activation keyword opcional — si se establece, el skill se queda fuera del prompt salvo que la query del usuario mencione una keyword. Este es el mecanismo de deferral del toolbag que evita que el registro de skills reviente la ventana de contexto del modelo.

Los skills se almacenan en un registry. El kernel de agente (graph por defecto) resuelve qué skills son visibles para el turno actual basándose en scope, RBAC y activation keywords. Aproximadamente 30 skills vienen de fábrica (bash, host_probe_*, query_promql, query_logs, query_traceql, expand_topology, find_topology_node, read_repo, search_knowledge, web_search, …).

Ver capacidad de skills; el formato del manifiesto está documentado bajo Skill manifest en la barra lateral de Reference. Los skills customizados se pueden cargar desde ONGRID_SKILLS_EXTERNAL_DIRS.

Base de conocimiento

Una base de conocimiento es una colección de documentos organizacionales que el agente puede buscar a través de search_knowledge. Los documentos se embedean una sola vez y se almacenan en Qdrant; la recuperación es híbrida (vector + BM25).

Las fuentes están en capas:

• vault — el knowledge integrado, solo lectura, empaquetado por Ongrid. Aproximadamente 100 playbooks Markdown que cubren diagnóstico de red, internals de Linux, recetas de Prometheus / Loki / Tempo, patrones comunes de incidentes. El vault se sincroniza desde el repo público ongridio/vault bajo demanda.
• upload — archivos Markdown, TXT, PDF, DOCX subidos por un admin de organización. Pasa por docextract y aterriza en el árbol de upload.
• manual — entradas escritas directamente en el editor de la UI.
• repo — repositorios Git completos sincronizados con SSH keys de solo lectura (ADR-023). Útil para ingestar tu propio repo de runbooks.

El agente llama a search_knowledge(query, k=N) y recibe chunks rankeados con metadata. Los embeddings los computa por defecto un modelo BGE empaquetado en ONNX offline (fast-bge-small-zh-v1.5); puedes cambiar a un embedder hosted (OpenAI, Zhipu, GLM…) vía Settings.

Ver capacidad de base de conocimiento.

Juntándolo todo

Un loop operacional típico:

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

• Un edge envía telemetría.
• Una regla de alerta la evalúa y produce un evento de alerta.
• El evento se agrupa en un incidente (o se ata a uno abierto).
• El incidente enruta a canales para notificación.
• Una investigación se inicia automáticamente (o la dispara un operador); el agente usa skills y la base de conocimiento para producir un informe.
• Una persona decide la voz + la paleta de herramientas con la que corre la investigación.

Todo el pipeline es observable: cada paso aparece en la timeline de la UI, cada llamada de skill está en el audit log, cada gasto de token está en el panel de presupuesto LLM.