コンセプト

このページでは Ongrid が用いる用語を依存順で紹介します。 クイックスタート を済ませた方には具体的な姿は 既に馴染みがあるはずですので、ここでは名前を付けていきます。

Edge

edge とは 1 つの稼働中 ongrid-edge プロセスのことです —— ホストごとに 1 つ。 登録、テレメトリ、リモート制御の単位です。

各 edge は以下を持ちます：

• サーバー生成の access key（半公開、edge を識別） と secret key（一度だけ表示、トンネル認証に使用）、
• frontier ブローカーのポート 40012 への アウトバウンド 長期 TCP 接続、
• 監督されるプラグインサブプロセス群（promtail、 node_exporter、process_exporter、otelcol-contrib）、
• 数秒ごとに刻むハートビート —— 停止すると ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD （デフォルト 90 秒）後に オフライン とマークされます。

edge は整数 edge_id（URL とエージェントツール呼び出しで使用）または name（UI と find_topology_node で使用）でアドレス指定されます。 list_edges で一覧、bash に edge_id=N を渡して特定 edge でコマンド実行、 query_promql にホストラベルを渡して PromQL クエリを 1 つの edge にスコープ、といったことが可能です。

重要：edge は デフォルトで読み取り専用 です。エージェントのホスト側スキルは インスペクション系（bash、host_probe_*、query_processes、 query_logs_tail、host_read_file）で、変更を行いません。書き込みアクションは 監査ログ付きの WebShell フローを通ります。

具体的なデプロイ手順は edge インストール と platforms / linux-edge を参照してください。

Device

device は edge より緩い概念です。edge は ongrid-edge プロセスと 1:1 ですが、 device は Ongrid が認識し、トポロジーに参加する任意のもの —— サービス、仮想ホスト、k8s pod、SD で発見された外部エンドポイントや手動インポート —— を含みます。

現状 UI は トポロジー ビューを通して device を暗黙に表示します。 device はトポロジーグラフ上のノードであり、edge、サービス、発見された外部システムは すべてノードです。expand_topology と find_topology_node スキルは device を対象に動作します —— 影響範囲（blast radius）の推論はこのグラフに依存します。

TIP

edge しかなければ、トポロジーグラフはホストノードの単層になります。 discover_services のようなスキルや k8s SD との統合がそれを埋めると、 ホストの上にサービスノードが現れ、横に外部エンドポイントが並ぶようになります。

Alert rule

alert rule は、テレメトリストリーム上で条件が成立するとアラートイベントを発火する 宣言的な仕様です。

Ongrid のルールモデルは 二次元 です：ルールは kind（評価するデータ型）と scope（評価する場所）を持ちます。

組み込み 14 kind をデータプレーン別にグループ化：

プレーン	Kind
ホストメトリクス	host_cpu、host_mem、host_disk、host_load、edge_offline、prom_ingest_fail
メトリクス/PromQL	promql_threshold、promql_burn_rate、promql_absence
ログ	log_match、log_volume
トレース	trace_latency、trace_error_rate
複合	composite_and（上記いずれかを AND）

ルールは以下を持ちます：

• kind のネイティブクエリ言語による condition、
• threshold + for duration（発火までに条件が保持される時間）、
• severity（critical / warning / info）、
• routing —— 通知を受け取るチャネル、オプションでクールダウン。

組み込みホストルール 6 件（host_cpu、host_mem、host_disk、 host_load、edge_offline、prom_ingest_fail）は ONGRID_ALERT_* 環境変数の 合理的なデフォルトでシードされ、UI から ON/OFF できます。カスタムルールは MySQL に保存され、 自由に編集できます。

アラート機能 を参照してください。 ルールスキーマは Reference サイドバーの Alert rule schema にあります。

Incident

incident は、同じ運用ストーリーに属するアラートイベントを高次にまとめたものです。 条件が成立するたびにアラートが発火するのに対し、incident は一度作られ、 関連するアラートが届くたびに更新されます。

incident は以下の単位です：

• investigation —— 1 incident に 1 つ以上の 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 report —— 確率順にランク付けされた 推定根本原因と証拠のリストです。

典型的な investigation は 5 つのサブエージェントを経由します：

1. incident-investigator（coordinator）—— incident を仮説に分解。
2. sre specialist —— SLO burn、最近のデプロイ、アラート相関を確認。
3. compute / disk / network specialist —— 影響を受けた edge に対するホストレベルプローブ。
4. ops specialist —— ナレッジベース検索、ランブックマッチング。
5. reviewer（critic loop）—— ドラフトレポートを再読し、サインオフ前に 不足する証拠を要求。

各ステップは UI の 推論タイムライン に記録されます —— すべてのツール呼び出し、消費したモデルトークン、サブエージェント発火が記録されます。 監査可能性が要点です。

任意の incident やチャットから手動で investigation を起動することもできます （「14:02 の order-service ドロップを調査して」）。出力先は同じ： incident に紐づいた investigation report です。

RCA 機能 を参照してください。investigation を実行する persona は Agents サイドバーの Incident investigator にあります。

Channel

channel は通知用に設定されたアウトバウンド宛先です。 「channel」は若干異なる 2 つの形を含みます：

• Webhook チャネル —— Slack incoming webhook、Larksuite (Feishu) webhook、DingTalk webhook、WeCom グループロボット、汎用 webhook。 これらは 片方向 —— Ongrid がカードを投稿するだけです。
• IM チャネル —— Telegram bot、Larksuite アプリ、DingTalk アプリ、 WeCom アプリ、Slack アプリ。これらは 双方向 —— 同じチャネルでアラートを配信するだけでなく、ユーザーが返信し、 エージェントに質問し、investigation をトリガーできます。

各 channel は以下を持ちます：

• name（自由形式）、type（slack / feishu / dingtalk / wecom / webhook / telegram）、endpoint マテリアル（URL + secret、 app token + chat ID、bot token + allow-from list…）。
• scope —— ここにルーティングされた通知を見られる組織 / ロール。 さらに任意の allow_from 送信者許可リスト（Telegram 専用）で ランダムな人がボットに話しかけられないように制御。
• default locale —— このチャネル上でエージェントが返信する言語 （UI のロケールから独立）。

channel はファーストクラスです：alert rule は名前で参照し、 エージェントは proactive メッセージを送れ、webhook URL を貼り直さずに 1 つの channel を複数ルールに紐付けできます。

チャネル概要 を参照してください。

IM channel（双方向）

別立てで取り上げる価値のある「channel」のサブタイプです。IM チャネル は チャット面（Telegram、Larksuite、DingTalk、WeCom、Slack）をフルなエージェントインターフェースに変えます。

双方向が具体的に意味するもの：

• エージェントが投稿可 —— アラート、investigation レポート、定期ダイジェスト。
• ユーザーが返信可 —— 質問（「ディスクが満杯になったのはなぜ？」）、 コマンド（「/list edges」）、フォローアップ（「それを調査して」）。
• 各メッセージは Web UI セッションと同じ user_agent と org にバインドされる —— 同じ RBAC、同じ監査ログ、同じスキルレジストリ。
• sender_allowlist（Telegram）またはアプリ権限ゲート（その他）が、 グループ内で誰がボットに話しかけられるかを決めます。

チャネル別の locale はここで重要になります。ユーザー向け UI のロケールが 英語でも、Telegram グループでは中国語で返信したい場合があります。これはチャネル単位で設定します。

最も柔軟な例として channels / telegram を参照してください。

Persona / agent

persona は設定可能なエージェントのアイデンティティです —— 以下を宣言する YAML/JSON：

• エージェントが好む モデル（サイトデフォルトをフォールバック）、
• 許可される スキル（スキルは scope: host、manager、org と、 class: safe、payload_read、payload_write を持ちます —— RBAC を参照）、
• エージェントの声色を定める システムプロンプト、
• 任意の サブエージェント 宣言（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 フォーマットは Reference サイドバーの Agent persona format にあります。カスタム persona は MySQL に保存され、 次のエージェント実行で読み込まれます。

Skill

skill はエージェントが呼び出せるツールです。各 skill は宣言します：

• name（例：query_promql、bash、expand_topology）、
• 引数と結果の JSON スキーマ、
• scope —— host（トンネル経由で特定の edge で実行）、 manager（manager プロセス内で実行）、org（edge をまたぐ manager skill）、
• class —— safe、payload_read、payload_write。読み取り専用クラスは 無制限、書き込みクラスは承認を経ます。
• 任意の activation keyword —— 設定されている場合、ユーザーの質問が キーワードを含むときだけスキルがプロンプトに表示されます。これは モデルのコンテキストウィンドウを skill registry で食い尽くさないようにする toolbag deferral 機構です。

スキルはレジストリに保存されます。エージェントカーネル（デフォルトは 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、…）が同梱されます。

スキル機能 を参照してください。マニフェストフォーマットは Reference サイドバーの Skill manifest にあります。カスタムスキルは ONGRID_SKILLS_EXTERNAL_DIRS から読み込めます。

ナレッジベース

ナレッジベース は、エージェントが search_knowledge で検索できる組織ドキュメント群です。 ドキュメントは一度埋め込まれ Qdrant に保存され、検索はハイブリッド（vector + BM25）です。

ソースはレイヤー化されています：

• vault —— Ongrid 同梱の組み込み読み取り専用ナレッジ。 ネットワーク診断、Linux 内部、Prometheus / Loki / Tempo レシピ、 典型的なインシデントパターンを扱う約 100 件の Markdown プレイブック。 vault は公開リポ ongridio/vault から オンデマンドで同期されます。
• upload —— 組織管理者がアップロードした Markdown、TXT、PDF、DOCX ファイル。 docextract を通り、upload ツリーに収まります。
• manual —— UI エディターで直接著作したエントリ。
• repo —— 読み取り専用 SSH キーで同期した Git リポジトリ全体（ADR-023）。 自社ランブックリポジトリを取り込むのに便利です。

エージェントは search_knowledge(query, k=N) を呼び、メタデータ付きの ランク済みチャンクを取得します。埋め込みはデフォルトでオフラインの ONNX 同梱 BGE モデル （fast-bge-small-zh-v1.5）で計算されます。Settings からホスト型エンベッダー （OpenAI、Zhipu、GLM…）に差し替え可能です。

ナレッジベース機能 を参照してください。

全体像

典型的な運用ループ：

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

• edge がテレメトリを送出。
• alert rule がそれを評価し、alert event を生成。
• イベントは incident にグループ化される（または既存のオープン incident に紐づく）。
• incident は通知のため channel にルーティング。
• investigation が自動起動（またはオペレーター起動）されると、 エージェントは skill と ナレッジベース を使ってレポートを生成。
• persona が investigation の声色とツールパレットを決定。

パイプライン全体は可観測です：各ステップは UI タイムラインに表示され、 各 skill 呼び出しは監査ログに残り、各トークン消費は LLM 予算パネルに記録されます。