Conceitos

Esta página apresenta os substantivos que o Ongrid usa, em ordem de dependência. Se você fez o Quickstart o formato concreto já será familiar; aqui colocamos nomes nele.

Edge

Um edge é um processo ongrid-edge rodando — um por host. É a unidade de enrollment, telemetria, e controle remoto.

Cada edge tem:

• uma access key gerada pelo servidor (semi-pública, identifica o edge) e uma secret key (mostrada uma vez, usada para autenticar o tunnel),
• uma conexão TCP outbound de longa duração ao broker frontier na porta 40012,
• uma frota de subprocessos plugin supervisionados (promtail, node_exporter, process_exporter, otelcol-contrib),
• um heartbeat que tique a cada poucos segundos — quando para, o edge é marcado offline após ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (padrão 90s).

Edges são endereçáveis por edge_id inteiro (usado em URLs e em chamadas de tool do agent) ou por name (usado na UI e por find_topology_node). Você pode listá-los via list_edges, rodar um comando em um específico via bash com edge_id=N, ou escopar uma query PromQL a um via query_promql com uma label de host.

Importante: um edge é read-only por padrão. As skills host-side do agent são de inspeção (bash, host_probe_*, query_processes, query_logs_tail, host_read_file) — não mutam. Ações de write passam pelo fluxo WebShell com audit logging.

Veja instalação do edge e platforms / linux-edge para os caminhos concretos de deploy.

Device

Um device é um conceito mais suave que um edge. Onde um edge mapeia 1:1 a um processo ongrid-edge, um device é qualquer coisa que o Ongrid sabe sobre que participa de uma topologia — incluindo serviços, hosts virtuais, pods k8s, e endpoints externos descobertos via SD ou importados manualmente.

Por enquanto a UI expõe devices implicitamente pela view de Topologia. Um device é um nó no grafo de topologia; edges, services, e sistemas externos descobertos são todos nós. As skills expand_topology e find_topology_node operam sobre devices — raciocínio de blast radius depende desse grafo.

TIP

Se você só tem edges até agora, seu grafo de topologia é uma única camada de nós de host. Conforme skills como discover_services e integrações com SD do k8s o populam, você verá nós de service aparecerem acima dos hosts e endpoints externos ao lado.

Alert rule

Uma alert rule é um spec declarativo que dispara um alerta quando uma condição vale em um stream de telemetria.

O modelo de rule do Ongrid é bidimensional: uma rule tem um kind (qual tipo de dado avalia) e um scope (onde avalia).

Os 14 kinds built-in, agrupados por data plane:

Plane	Kinds
Host metrics	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
Traces	trace_latency, trace_error_rate
Composto	composite_and (qualquer das anteriores, AND-ado)

Rules carregam:

• uma condição na linguagem de query nativa do kind,
• um threshold + duração for (quanto a condição precisa durar antes de disparar),
• uma severity (critical / warning / info),
• um routing — quais canais recebem notificações, com cooldown opcional.

As 6 rules de host built-in (host_cpu, host_mem, host_disk, host_load, edge_offline, prom_ingest_fail) são semeadas com defaults sensatos de env vars ONGRID_ALERT_* e você pode ligar/desligar pela UI. Rules custom vivem no MySQL e podem ser editadas livremente.

Veja capacidade de alertas; o schema de rule está documentado em Alert rule schema na sidebar de Reference.

Incident

Um incident é um agrupamento de ordem mais alta de alert events que pertencem à mesma história operacional. Onde um alerta dispara cada vez que a condição vale, um incident é criado uma vez e atualizado conforme alertas relacionados chegam.

Incidents são a unidade de:

• investigação — um incident, uma ou mais investigações.
• paging — roteamento de canal acontece no momento de criação do incident, não por alerta.
• timeline — a página de detalhe do incident é o registro cronológico de cada alert event, ação de agent, e nota de operador atadas à mesma história.
• closure — incidents passam por open → investigating → mitigated → resolved (ou false_positive). Mudanças de estado são audit-logged.

A lógica de agrupamento é intencionalmente simples agora: por tupla {rule_id, edge_id} com uma janela de atividade de 1 hora. O roadmap é tornar isso configurável (group_by) por rule.

Investigação

Uma investigação é um run estruturado de agent atado a um incident. A saída é um investigation report em Markdown — uma lista ordenada de causas raiz prováveis mais evidências.

Uma investigação típica percorre cinco sub-agents:

1. incident-investigator (coordinator) — decompõe o incident em hipóteses.
2. specialist sre — checa burn de SLO, deploys recentes, correlação de alerta.
3. specialists compute / disk / network — probing a nível de host nos edges afetados.
4. specialist ops — lookup de base de conhecimento, correspondência de runbook.
5. reviewer (loop crítico) — re-lê o draft do report e pede evidência faltante antes do signoff.

Cada passo é gravado na timeline de reasoning na UI — cada chamada de tool, cada token de modelo gasto, cada dispatch de sub-agent. Auditabilidade é o ponto.

Você também pode lançar uma investigação manualmente de qualquer incident ou do chat ("investigue o drop do order-service às 14:02"). A saída vai pro mesmo lugar: um investigation report atado a um incident.

Veja capacidade RCA; a persona que roda investigações está documentada em Incident investigator na sidebar de Agents.

Canal

Um canal é um destino outbound configurado para notificações. "Canal" cobre dois formatos ligeiramente diferentes:

• Canais webhook — Slack incoming webhooks, Larksuite (Feishu) webhooks, DingTalk webhooks, robots de grupo WeCom, webhook genérico. Esses são one-way — o Ongrid posta um card e é só.
• Canais IM — Bot Telegram, app Larksuite, app DingTalk, app WeCom, app Slack. Esses são two-way — o mesmo canal tanto entrega alertas QUANTO permite ao usuário responder, perguntar ao agent, disparar uma investigação.

Cada canal tem:

• um name (free-form), type (slack / feishu / dingtalk / wecom / webhook / telegram), e endpoint (URL + secret, ou app token + chat ID, ou bot token + allow-from list…).
• um scope — qual org / quais roles podem ver notificações roteadas aqui. Mais uma allow_from opcional de sender allowlist (Telegram especificamente) para que pessoas aleatórias não possam falar com seu bot.
• um default locale — em qual idioma o agent responde nesse canal, independente do locale da UI.

Canais são first-class: alert rules referem-se a eles por nome, o agent pode enviar mensagens proativas para eles, e você pode conectar um canal a múltiplas rules sem recolar URLs de webhook.

Veja visão geral dos canais.

Canal IM (two-way)

Um subtipo de "canal" que vale destacar separadamente. Um canal IM transforma uma superfície de chat (Telegram, Larksuite, DingTalk, WeCom, Slack) em uma interface completa de agent.

O que two-way significa concretamente:

• O agent pode postar — alertas, investigation reports, digests agendados.
• O usuário pode responder — perguntas ("por que o disco encheu?"), comandos ("/list edges"), follow-ups ("investigate that").
• Cada mensagem é vinculada ao mesmo user_agent e org que a sessão da Web UI — mesmo RBAC, mesmo audit log, mesmo skill registry.
• Um sender_allowlist (Telegram) ou gate de permissão de app (os outros) decide quem é permitido falar com o bot em um grupo.

Locale por canal importa aqui. O locale da UI voltada ao usuário pode ser inglês; um grupo Telegram ainda pode querer respostas em chinês; você define isso por canal.

Veja channels / telegram para o exemplo mais flexível.

Persona / agent

Uma persona é uma identidade configurável de agent — uma declaração YAML/JSON de:

• qual modelo o agent prefere (com default do site como fallback),
• quais skills são permitidas (skills carregam um scope: host, manager, org, e uma class: safe, payload_read, payload_write — veja RBAC),
• um system prompt na voz do agent,
• declarações opcionais de sub-agent (uma persona coordinator pode dar spawn em personas specialist).

O Ongrid distribui várias personas de fábrica:

• coordinator — o padrão; decompõe perguntas de usuário, roteia a specialists ou roda skills direto.
• incident-investigator — coordinator de modo incident; percorre topologia, correlaciona sinais, redige um report.
• sre, network, compute, disk, ops — specialists invocados pelos coordinators.
• reviewer — loop crítico para o draft do incident-investigator.

Você pode escrever a sua própria. O formato de persona está documentado em Agent persona format na sidebar de Reference. Personas custom pousam no MySQL; são pegadas no próximo run de agent.

Skill

Uma skill é uma tool callable que o agent pode invocar. Toda skill declara:

• um name (ex.: query_promql, bash, expand_topology),
• um JSON schema para argumentos e resultado,
• um scope — host (roda em um edge específico pelo tunnel), manager (roda no processo manager), ou org (skill manager cross-edge),
• uma class — safe, payload_read, payload_write. Classes read-only são irrestritas; classes write passam por aprovação.
• uma palavra-chave de ativação opcional — se setada, a skill fica fora do prompt a menos que a query do usuário mencione uma keyword. É o mecanismo de toolbag deferral que evita que o skill registry estoure a janela de contexto do modelo.

Skills são armazenadas em um registry. O agent kernel (kernel graph por padrão) resolve quais skills são visíveis para o turn atual baseado em scope, RBAC, e activation keywords. Aproximadamente 30 skills vêm de fábrica (bash, host_probe_*, query_promql, query_logs, query_traceql, expand_topology, find_topology_node, read_repo, search_knowledge, web_search, …).

Veja capacidade de skills; o formato de manifesto está documentado em Skill manifest na sidebar de Reference. Skills custom podem ser carregadas de ONGRID_SKILLS_EXTERNAL_DIRS.

Base de conhecimento

Uma base de conhecimento é uma coleção de documentos da organização que o agent pode buscar via search_knowledge. Documentos são embedados uma vez e armazenados no Qdrant; a retrieval é híbrida (vector + BM25).

Fontes são em camadas:

• vault — o conhecimento built-in, read-only empacotado pelo Ongrid. Aproximadamente 100 playbooks Markdown cobrindo diagnóstico de rede, internos do Linux, receitas Prometheus / Loki / Tempo, padrões comuns de incident. O vault sincroniza com o repo público ongridio/vault sob demanda.
• upload — arquivos Markdown, TXT, PDF, DOCX enviados por um admin da org. Passa pelo docextract e pousa na árvore de upload.
• manual — entradas escritas diretamente no editor da UI.
• repo — repositórios Git inteiros sincronizados com chaves SSH read-only (ADR-023). Útil para ingerir seu próprio repo de runbook.

O agent chama search_knowledge(query, k=N) e recebe de volta chunks ordenados com metadados. Embeddings são computados por um modelo BGE ONNX-bundled offline por padrão (fast-bge-small-zh-v1.5); você pode trocar por um embedder hospedado (OpenAI, Zhipu, GLM…) via Settings.

Veja capacidade base de conhecimento.

Juntando tudo

Um loop operacional típico:

  edge ─▶ telemetria ─▶ alert rule ─▶ alert event ─▶ incident
                                                       │
                                              ┌────────┴────────┐
                                              ▼                 ▼
                                       investigação        canal
                                       (agent + skills)    (Slack / TG /
                                              │              IM …)
                                              ▼
                                       investigation
                                       report

• Um edge envia telemetria.
• Uma alert rule avalia e produz um alert event.
• O event é agrupado em um incident (ou anexado a um aberto).
• O incident roteia para canais para notificação.
• Uma investigação é auto-iniciada (ou disparada por operador); o agent usa skills e a base de conhecimento para produzir um report.
• Uma persona decide a voz + paleta de tool com que a investigação roda.

Todo o pipeline é observável: cada passo aparece na timeline da UI, cada chamada de skill está no audit log, cada gasto de token está no painel de budget do LLM.