개념

이 페이지에서는 Ongrid 가 사용하는 명사들을 의존 순서대로 소개합니다. Quickstart 를 마쳤다면 구체적인 형태는 이미 익숙할 것입니다. 여기서는 이름을 붙입니다.

Edge

edge 는 실행 중인 ongrid-edge 프로세스 하나 — 호스트당 한 개입니다. 등록, 텔레메트리, 원격 제어의 단위입니다.

각 edge 는 다음을 가집니다.

서버가 생성한 access key (공개에 가까운, edge 식별자) 와 secret key (한 번만 표시되며 터널 인증에 사용),
frontier 브로커의 40012 포트에 대한 장시간 유지되는 아웃바운드 TCP 연결,
감독되는 플러그인 서브프로세스 (promtail, node_exporter, process_exporter, otelcol-contrib) 군,
몇 초 간격의 하트비트 — 멈추면 ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (기본 90s) 후 edge 는 오프라인으로 표시됩니다.

Edge 는 정수형 edge_id (URL 과 에이전트 도구 호출에서 사용) 또는 name (UI 와 find_topology_node 에서 사용) 로 주소 지정할 수 있습니다. list_edges 로 나열하고, bash 에 edge_id=N 을 주어 특정 edge 에서 명령을 실행하고, query_promql 에 호스트 레이블을 줘서 PromQL 쿼리를 한 edge 로 한정할 수 있습니다.

중요한 점: edge 는 기본적으로 읽기 전용입니다. 에이전트의 호스트 측 기능은 점검용 (bash, host_probe_*, query_processes, query_logs_tail, host_read_file) 이며, 변경하지 않습니다. 쓰기 액션은 감사 로깅이 붙은 WebShell 흐름을 거칩니다.

구체적인 배포 경로는 edge install 와 platforms / linux-edge 를 참고하세요.

Device

device 는 모니터링되는 물리 또는 가상 호스트 — 머신 자체이며, 그 위에서 동작하는 agent 프로세스가 아닙니다.

device 는 다음 호스트 정보를 보유합니다:

hostname, 운영 체제, OS 버전, 커널 버전, CPU 아키텍처,
용량: CPU 수, 전체 RAM, 전체 디스크,
실시간 사용률: CPU %, 메모리 %, 디스크 %,
운영자가 지정한 role (server / storage / network / database — 다중 역할 호스트는 동시에 여러 개를 가질 수 있음),
안정적인 fingerprint — hostname 을 변경해도 device 의 이력이 유지됨,
비정규화된 online 상태 + last_seen_at — 그 위에서 동작하는 edge 와 동기화.

device 와 edge 는 서로 다른 것입니다. edge 는 ongrid-edge agent 프로세스 — agent 신원, access key, 터널 상태. device 는 그 agent 가 동작하는 호스트 본체 — 하드웨어, OS, 현재 부하. 둘은 edge_devices 를 통해 다대다로 연결됩니다: 오늘날 대부분의 설치는 호스트 하나에 edge 하나 (1:1) 이지만, 분리해 둔 이유는 향후 한 호스트에서 여러 agent 를 동시에 운영해도 호스트 지표 이력이 손실되지 않게 하고, edge 의 access key 를 회전하더라도 호스트 동일성을 유지하기 위함입니다.

device 는 토폴로지 그래프에서 type=device 노드로 나타납니다. 토폴로지에는 다른 노드 유형도 있습니다 (service, cluster, app, …); device 는 그중 하나이지 상위 개념이 아닙니다. expand_topology 의 영향 범위 BFS 는 모든 노드 유형을 넘나듭니다 — device 에서 아래로 그 위에 동작하는 서비스와 pod 까지, service 에서 위로 그것을 호스팅하는 device 까지.

알림 규칙

알림 규칙 은 텔레메트리 스트림에서 조건이 성립할 때 알림 이벤트를 발생시키는 선언적 명세입니다.

Ongrid 의 규칙 모델은 2 차원입니다. 규칙은 kind (어떤 데이터 타입을 평가) 와 scope (어디서 평가) 를 갖습니다.

내장된 14 개 kind, 데이터 플레인별 분류:

Plane	Kinds
호스트 메트릭	`host_cpu`, `host_mem`, `host_disk`, `host_load`, `edge_offline`, `prom_ingest_fail`
Metric/PromQL	`promql_threshold`, `promql_burn_rate`, `promql_absence`
로그	`log_match`, `log_volume`
트레이스	`trace_latency`, `trace_error_rate`
복합	`composite_and` (위 항목 중 다수의 AND)

규칙은 다음을 담습니다.

해당 kind 의 네이티브 쿼리 언어로 작성된 condition,
threshold + for 지속 시간 (발화 전 조건이 유지되어야 하는 시간),
severity (critical / warning / info),
routing — 어느 채널이 알림을 받을지, 선택적 cooldown 포함.

6 개 내장 호스트 규칙 (host_cpu, host_mem, host_disk, host_load, edge_offline, prom_ingest_fail) 은 ONGRID_ALERT_* 환경 변수에서 적절한 기본값으로 시드되며 UI 에서 켜고 끌 수 있습니다. 커스텀 규칙은 MySQL 에 살고 자유롭게 편집 가능합니다.

알림 기능 을 참고하세요. 규칙 스키마는 Reference 사이드바의 Alert rule schema 에 문서화되어 있습니다.

Incident

incident 는 같은 운영 이야기에 속하는 알림 이벤트들의 상위 그룹입니다. 알림이 조건이 성립할 때마다 발생하는 반면, incident 는 한 번 생성되어 관련 알림이 도착하면 갱신됩니다.

Incident 는 다음의 단위입니다.

investigation — 한 incident 에 하나 이상의 investigation.
paging — 채널 라우팅은 incident 생성 시점에 일어나며, 알림 단위가 아닙니다.
timeline — incident 상세 페이지는 같은 이야기에 묶인 모든 알림 이벤트, 에이전트 액션, 운영자 노트의 시간순 기록입니다.
closure — incident 는 open → investigating → mitigated → resolved (또는 false_positive) 를 거칩니다. 상태 변경은 감사 로그에 남습니다.

그룹핑 로직은 지금은 의도적으로 단순합니다. {rule_id, edge_id} 튜플과 1 시간 활동 윈도우 기준입니다. 로드맵은 규칙별로 (group_by) 구성 가능하게 하는 것입니다.

Investigation

investigation 은 incident 에 부착된 구조화된 에이전트 실행입니다. 출력은 Markdown investigation 보고서 — 추정 근본 원인의 순위 리스트와 증거입니다.

전형적인 investigation 은 5 개의 서브 에이전트를 거칩니다.

incident-investigator (coordinator) — incident 를 가설들로 분해.
sre specialist — SLO 소진, 최근 배포, 알림 상관 분석.
compute / disk / network specialist — 영향 받은 edge 의 호스트 레벨 점검.
ops specialist — 지식 베이스 조회, 플레이북 매칭.
reviewer (critic loop) — 초안 보고서를 다시 읽어 사인오프 전 누락된 증거를 요청.

각 단계는 UI 의 추론 타임라인 에 기록됩니다 — 모든 도구 호출, 소비된 모든 모델 토큰, 모든 서브 에이전트 디스패치. 감사 가능성이 핵심입니다.

incident 또는 채팅 ("investigate the order-service drop at 14:02") 에서 investigation 을 수동으로 띄울 수도 있습니다. 출력은 같은 곳으로 갑니다: incident 에 묶인 investigation 보고서.

RCA 기능 을 참고하세요. investigation 을 구동하는 persona 는 Agents 사이드바의 Incident investigator 에 문서화되어 있습니다.

Channel

channel 은 알림에 대해 구성된 아웃바운드 목적지입니다. "channel" 은 두 가지 다소 다른 형태를 포함합니다.

Webhook channel — Slack incoming webhooks, Larksuite (Feishu) webhooks, DingTalk webhooks, WeCom 그룹 로봇, 일반 webhook. 단방향 입니다 — Ongrid 가 카드를 게시하고 끝.
IM channel — Telegram 봇, Larksuite 앱, DingTalk 앱, WeCom 앱, Slack 앱. 양방향 입니다 — 같은 채널이 알림을 전달하고 사용자가 답장하고 에이전트에 질문하고 investigation 을 트리거할 수 있습니다.

각 채널은 다음을 가집니다.

name (자유형), type (slack / feishu / dingtalk / wecom / webhook / telegram), endpoint 자료 (URL + secret, 또는 앱 토큰 + chat ID, 또는 봇 토큰 + allow-from 리스트…).
scope — 어느 조직 / 어느 롤이 여기로 라우팅된 알림을 볼 수 있는지. 또한 선택적 allow_from 발신자 화이트리스트 (특히 Telegram) 로 임의의 사람이 봇과 대화할 수 없게 합니다.
default locale — 이 채널에서 에이전트가 응답하는 언어, UI 로케일과 독립.

채널은 일급 시민입니다. 알림 규칙이 이름으로 채널을 참조하고, 에이전트가 선제적으로 메시지를 보낼 수 있으며, 한 채널을 여러 규칙에 webhook URL 을 재붙여 넣지 않고도 연결할 수 있습니다.

채널 개요 를 참고하세요.

IM 채널 (양방향)

별도로 강조할 가치가 있는 "channel" 의 서브타입입니다. IM 채널은 채팅 표면 (Telegram, Larksuite, DingTalk, WeCom, Slack) 을 완전한 에이전트 인터페이스로 바꿉니다.

양방향이 구체적으로 의미하는 것:

에이전트가 게시할 수 있다 — 알림, investigation 보고서, 예약된 다이제스트.
사용자가 답장할 수 있다 — 질문 ("왜 디스크가 꽉 찼지?"), 명령 ("/list edges"), 후속 ("investigate that").
모든 메시지는 Web UI 세션과 동일한 user_agent 와 org 에 바인딩됩니다 — 동일한 RBAC, 동일한 감사 로그, 동일한 기능 레지스트리.
sender_allowlist (Telegram) 또는 앱 권한 게이트 (그 외) 가 그룹에서 봇과 대화 가능한 사람을 결정합니다.

채널별 locale 이 여기서 중요합니다. 사용자 대면 UI 로케일이 영어더라도 Telegram 그룹은 여전히 한국어 응답을 원할 수 있고, 이를 채널별로 설정합니다.

가장 유연한 예시는 channels / telegram 을 참고하세요.

Persona / agent

persona 는 구성 가능한 에이전트 정체성입니다 — YAML/JSON 선언으로 다음을 정합니다.

에이전트가 선호하는 model (사이트 기본을 폴백으로),
허용된 기능 (기능은 scope 를 가집니다: host, manager, org, 그리고 class: safe, payload_read, payload_write — RBAC 참고),
에이전트의 어조로 작성된 system prompt,
선택적 서브 에이전트 선언 (coordinator persona 가 specialist persona 를 띄울 수 있음).

Ongrid 는 여러 persona 를 기본 제공합니다.

coordinator — 기본; 사용자 질문을 분해하고 specialist 로 라우팅하거나 기능을 직접 실행.
incident-investigator — incident 모드 coordinator; 토폴로지를 따라가고, 신호를 상관 분석하고, 보고서를 작성.
sre, network, compute, disk, ops — coordinator 들이 호출하는 specialist 들.
reviewer — incident-investigator 의 초안에 대한 critic loop.

자체 persona 도 작성할 수 있습니다. Persona 포맷은 Reference 사이드바의 Agent persona format 에 문서화되어 있습니다. 커스텀 persona 는 MySQL 에 저장되고, 다음 에이전트 실행에서 픽업됩니다.

Skill (기능)

기능 (skill) 은 에이전트가 호출할 수 있는 도구입니다. 각 기능은 다음을 선언합니다.

name (예: query_promql, bash, expand_topology),
인자와 결과의 JSON schema,
scope — host (터널을 통해 특정 edge 에서 실행), manager (manager 프로세스 내에서 실행), org (cross-edge manager 기능),
class — safe, payload_read, payload_write. 읽기 전용 클래스는 제한이 없고 쓰기 클래스는 승인을 거칩니다.
선택적 activation keyword — 설정되면 사용자 쿼리가 키워드를 언급하지 않는 한 기능은 프롬프트에 들어가지 않습니다. 기능 레지스트리가 모델 컨텍스트 윈도우를 초과하지 않도록 유지하는 toolbag 디퍼럴 메커니즘입니다.

기능은 레지스트리에 저장됩니다. 에이전트 커널 (기본 graph 커널) 이 현재 턴에서 어떤 기능이 보이는지를 scope, RBAC, activation keyword 에 기반해 해석합니다. 약 30 개 기능이 기본 제공됩니다 (bash, host_probe_*, query_promql, query_logs, query_traceql, expand_topology, find_topology_node, read_repo, search_knowledge, web_search, …).

기능 capability 를 참고하세요. 매니페스트 포맷은 Reference 사이드바의 Skill manifest 에 문서화되어 있습니다. 커스텀 기능은 ONGRID_SKILLS_EXTERNAL_DIRS 에서 로딩 가능합니다.

지식 베이스

지식 베이스는 에이전트가 search_knowledge 로 검색할 수 있는 조직 문서의 모음입니다. 문서는 한 번 임베딩되어 Qdrant 에 저장되고, 검색은 하이브리드 (벡터 + BM25) 입니다.

소스는 계층화되어 있습니다.

vault — Ongrid 가 번들로 제공하는 내장 읽기 전용 지식 베이스. 네트워크 진단, Linux 내부, Prometheus / Loki / Tempo 레시피, 흔한 incident 패턴을 다루는 대략 100 개의 Markdown 플레이북. vault 는 공개 ongridio/vault 저장소에서 요청 시 동기화됩니다.
upload — 조직 관리자가 업로드한 Markdown, TXT, PDF, DOCX 파일. docextract 를 거쳐 업로드 트리에 들어갑니다.
manual — UI 에디터에서 직접 작성한 항목.
repo — 읽기 전용 SSH 키 (ADR-023) 로 동기화된 전체 Git 저장소. 자신의 runbook 저장소를 인제스트하는 데 유용합니다.

에이전트는 search_knowledge(query, k=N) 을 호출하여 메타데이터가 붙은 순위화된 청크를 받습니다. 임베딩은 기본적으로 오프라인 ONNX 번들 BGE 모델 (fast-bge-small-zh-v1.5) 로 계산됩니다. 설정에서 호스팅 임베더 (OpenAI, Zhipu, GLM…) 로 교체할 수 있습니다.

지식 베이스 capability 를 참고하세요.

종합

전형적인 운영 루프:

text

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

edge 가 텔레메트리를 송출한다.
알림 규칙 이 평가하여 알림 이벤트를 만든다.
이벤트는 incident 로 그룹핑된다 (또는 열린 incident 에 부착).
incident 는 알림을 위해 채널 로 라우팅된다.
investigation 이 자동 시작 (또는 운영자 트리거) 된다. 에이전트가 기능 과 지식 베이스 를 사용해 보고서를 만든다.
persona 가 investigation 이 실행되는 어조와 도구 팔레트를 결정한다.

전체 파이프라인은 관측 가능합니다. 모든 단계가 UI 타임라인에 나타나고, 모든 기능 호출이 감사 로그에 남고, 모든 토큰 소비가 LLM 예산 패널에 표시됩니다.

개념 ​

Edge ​

Device ​

알림 규칙 ​

Incident ​

Investigation ​

Channel ​

IM 채널 (양방향) ​

Persona / agent ​

Skill (기능) ​

지식 베이스 ​

종합 ​

개념