トラブルシュートと AI RCA

監視は、何かがおかしいということを教えてくれます。Troubleshoot セクションはその次の問い — 何がおかしいのか、そしてなぜか — のためにあります。Yagra がすでに収集したデータを掘り下げる オンデマンド分析のカタログと、インシデントの証拠を文章による根本原因の説明に変える、オプトイン の AI レイヤーです。

オンデマンド分析

トラブルシュート分析は、Yagra 自身のストアに対する読み取り専用のジョブです — メトリクスの 時系列データベース、パッシブイベントのログストア、トラフィックフローのストア。機器には一切 触れません。追加のポーリングも、設定の読み取りも、診断対象のネットワークへ向けたトラフィックの 発生もありません。おかげで分析はインシデントの真っ最中でも安全に実行できます — まさに実行したい のはその瞬間です。

分析はトラブルシュート ▸ 診断ツールから、ツール・範囲・深さを選んで起動します。

• 範囲 — all（インベントリ全体）、group（1 つのグループの直接のメンバー）、node （単一ノード）。範囲のピッカーはサーバー側でフリートを検索するため、数万台の中から 1 台を 見つける操作はスクロールではなく先行入力です。
• 深さ — ジョブが調べるノード数です。quick はスキャンを 20 ノードに、standard（既定）は 60 ノードに制限し、exhaustive は上限をフリート全体を覆えるところまで引き上げます。深い スキャンほど時間がかかります。quick は最初の一手が数秒で返ってくるために存在します。
• チューニング — ほとんどのツールは、対象期間、比較対象のベースライン期間、感度の設定、 そして（メトリクス系ツールでは）到達性／インターフェースのメトリクスだけ、あるいはシステム メトリクスだけをスキャンするメトリクスファミリのフィルタも受け付けます。「この 1 時間を直近 1 日と比較する」「大きな逸脱だけを浮かび上がらせる」はつまみであって、別のツールではありません。

ジョブは非同期に実行されます。実行中のジョブはライブで確認でき、キャンセルもできます。ジョブは 実行中・完了・失敗・キャンセルのいずれかの状態でトラブルシュート ▸ 分析ジョブに残ります。 各ジョブが返す分析結果には上限があり — 1 回の実行あたり最大 60 件 — フリート全体のスキャンでも、 データの山ではなく読める長さの候補リストになります。

カタログ

分析は 4 つのファミリにまたがる 15 種類あります。ストアごとに 1 ファミリ、加えてそれらを 横断して読むファミリが 1 つです。

メトリクス分析は時系列ストアを読みます。

分析	何を探すか
anomaly	ベースラインからの逸脱のスコアリング — 自分自身の履歴と違う振る舞いをしているメトリクス
correlation	ある期間内で一緒に動く系列 — 同時に何が変わったのか
capacity	枯渇までの時間の予測 — どのリソースが尽きるのか、そしておおよそいつか
flap	到達性とリンク状態の揺れ — 上がったままにも下がったままにもならないインターフェースとノード

パッシブイベント分析は syslog / トラップのイベントストアを読みます。

分析	何を探すか
event_storm	ノード自身のベースラインに対する、ノード単位でのイベント量の急増
event_flap	1 つのノードで同じイベントルールが発生と解消を繰り返している状態
severity_shift	ノードの syslog 重大度の内訳が error / critical 側に偏っている状態
rule_gap	大量に発生している未一致イベントをシグネチャでクラスタリング — ルールカバレッジの欠落
auth_probe	認証失敗を送信元ごとにクラスタリング — ブルートフォース、あるいは設定を誤った NMS

フロー分析はトラフィックフローのストアを読みます。

分析	何を探すか
traffic_anomaly	ベースラインを外れたノードまたはインターフェースのフロー量
talker_shift	ベースライン期間と比べて新たに支配的になったトーカーや会話
new_destination	ベースライン期間には無かった宛先 AS やポートへのトラフィック
flow_scan	1 つの送信元が異常に多くの異なる宛先やポートに接触している状態 — スキャンやワームの挙動

クロスストア分析はメトリクス・イベント・フローを組み合わせます。

分析	何を探すか
saturation	多忙なノードのトラフィックを単一の会話が占有している状態 — リンクの独占者
incident_correlate	1 ノードについてのクロスシグナルなインシデントタイムライン: メトリクスの異常、イベント、フローの変化を到着順に

インシデントの最中にまず手を伸ばすべきなのが incident_correlate です。シグナルが届いた順序こそ が原因を指し示すことは多く、このツールはその順序を組み立ててくれます。

各ファミリは自分のストアを読むので、そのストアが持っているものしか見つけられません。パッシブ イベント分析は syslog / トラップの受信がイベントを受け取っていて初めて材料を持ち、フロー分析は フローエクスポートが設定されていて初めて材料を持ちます。メトリクス分析はどのデプロイでも動きます — 時系列ストアはオプションではありません。

分析の実行

分析の実行には Operator 以上のロールが必要です — 具体的にはアラート確認（ACK）の権限、 つまりアラートを確認したりミュートしたりできるのと同じ権限です。これはどちらの入口にも 当てはまります。REST API でも MCP でも同じなので、Viewer スコープの API トークン では AI クライアント経由でも分析を起動できません。実行のキャンセルにも同じ権限が必要です。過去の 実行とその分析結果の閲覧に必要なのは Viewer ロールだけです — 分析は設定を一切変更しないので、 その結果はダッシュボードと同じくらい開かれています。

大規模なフリートに対する徹底的な分析はストアにとって実際の負荷になるため、ランナーは受付制御 を適用します。

• 同時に実行できる分析は最大 4 件です（YAGRA_ANALYSIS_MAX_CONCURRENT）。
• スライディングウィンドウで、1 分あたりに開始できる新規ジョブは最大 30 件です （YAGRA_ANALYSIS_RATE_PER_MIN）。
• どちらかの上限に達すると、API は作業を積み上げる代わりに HTTP 429 を返します — クライアントはバックオフして再試行してください。

既定値は数千ノードを監視するコア 1 台構成に合わせてあります。ハードウェアや運用の流儀が違うなら、 どちらも環境変数です。

この上限はあらゆる入口に等しく効きます。WebUI、REST API、MCP は 1 つのランナーを 共有するため、熱心すぎる AI クライアントのせいで人間のオペレーターの分析が後回しになることはありません — 同じ 429 に当たります。MCP から起動された分析は、実行したトークンの識別情報とともに監査ログにも 記録されます。

結果の読み方

15 種類の分析にはそれぞれ専用のレポート画面があり、その分析にしか出てこない結果に合わせて 作られています — キャパシティの予測はログ行の一覧ではありませんし、レポートもそのふりをしません。 「専用」が何を意味するのか、いくつか例を挙げます。

• incident_correlate はインシデントタイムラインを描画します — シグナルを到着順にプロット します。
• flow_scan はスキャンの形状を散布図で描くため、ワームのファンアウトのパターンは推測ではなく 目に見えます。
• saturation はキャパシティの文脈つきのシェアメーターを表示します。1 つの会話がそのリンクを どれだけ占めているかです。

分析結果は対象のノードへリンクで戻れます。どのレポートも CSV エクスポートに対応し、それぞれ に共有できるディープリンク（?job=）があります — インシデント対応のチャンネルに貼れば、 同僚は説明ではなく同じレポートそのものを開きます。ディープリンクはジョブを直接解決するため、 最近の一覧から流れてしまった実行へのリンクでも開けますし、誤ったツールの下に貼られたリンクは、 実際にそれを読めるレポートへリダイレクトされます。

過去の実行はトラブルシュート ▸ 分析ジョブに残るため、判断の根拠になった証拠はインシデントが 収束した後からでも見直せます。

検出結果を横断して探す

1 回の実行が答えるのは「この分析が何を見つけたか」です。実際に知りたいのはたいてい逆向きの 問い — 「このスイッチについて、あるいはこのサイトについて、最近何か検出されていないか」 — で、 これは単一の実行では答えられません。

トラブルシュート ▸ 保存済み分析結果は、全実行を横断して検出結果を新しい順に検索します。ノード／ サイト、分析種別、重大度、期間で絞り込めます。各行はそれを生成した実行のレポートへリンクするので、 気になる検出結果からその全体像までは 1 クリックです。一覧はキーセットページングなので、運用期間 がどれだけ長くなっても実用に耐えます。

分析をスケジュール実行する

誰かが見ているかどうかに関わらず回しておきたい分析があります — 夜間の異常検知、週次のキャパシティ 予測など。トラブルシュート ▸ 定期実行は、毎日／毎週／毎月の指定時刻（UTC）に、フリート全体・ 単一サイト・単一ノードのいずれかを対象として分析を実行します。ウィンドウや感度の設定は手動実行と 同じです。

スケジュールの作成・編集に必要な権限は実行と同じ（Operator 以上）です。知っておくべき挙動が 2 点あります。

• 拒否された発火はスキップではなく延期されます。 スケジュールの実行時刻に実行制御 （受付制御）が満杯だった場合、その回は起動されませんが、スケジュールは due のまま残り、 次の 1 分後の tick で再試行されます。混雑した一瞬が奪うのは 1 分であって、1 周期まるごとでは ありません。一覧ではその試行を「延期」として表示し、失敗とは区別します。
• フローストアの無い環境ではトラフィックフロー系の分析をスケジュールできません。 ClickHouse が未設定の場合、フロー分析は「フロー層が有効ではありません」という 1 行を返します。 1 度きりの問いへの答えとしては妥当ですが、毎晩問い続ければ空の実行が延々と積み上がるだけです。 そのためスケジュールの選択肢には出さず、API も拒否します。

スケジュールの通知は既定でオフです（手動実行は結果を待っている人がいるため既定でオン）。

AI による根本原因分析

分析群の上には、オプトインの AI レイヤーが乗ります。LLM が、Yagra 自身のデータに根ざした インシデントの根本原因の説明を書きます。アクティブアラートから、Operator は Yagra に「この インシデントを説明して」と依頼できます。Yagra は証拠 — アラート、影響を受けたノードの事実、 依存関係グラフ上でのその位置、障害前後のクロスシグナルなタイムライン — を組み立て、設定した モデルへ送り、構造化された回答を返します。要約、推定される根本原因、影響を受ける配下のノード、 次に取るべき手順の提案、そして確度の見積りです。

設計上の選択を 2 つ挙げておきます。

• 説明するのは根本原因であって、クリックした症状ではありません。 起点にしたアラートが親の 障害の下で抑制されている子だった場合、説明は親を対象にします — アラートパイプラインがすでに 計算している、あの根本原因ロールアップと同じです（アラートを 参照）。
• 根拠は Yagra がすでに保持している証拠で、さらに自分で取りに行けます。 モデルはインシデントの コンテキストから出発し、v0.1.23 以降は Yagra の読み取り専用 MCP ツールを 通じて自分で調べることもできます — インターフェースの系列を引く、そもそもポーラーが生きて いたか確かめる、syslog に何が出ていたか読む、発火したしきい値を見る、といった具合です。以前は決まった facts を渡されて一発で答える形だったため、あらかじめ含めると決めたものについてしか推論できません でした。モデル自身のネットワークアクセスや、機器に触れる能力は依然としてありません。

AI RCA は既定で無効で、ここでの「無効」は存在しないという意味です。 プロバイダを設定して いなければ、クライアントも、保存された認証情報も、外向き通信もありません — 生きた連携の手前 でフィーチャーフラグが落ちている、という話ではありません。プロバイダを有効化するまで WebUI は 「説明する」操作を表示しませんし、未設定のシステムでは API が RCA のリクエストに 503 を返します。

設定は設定 ▸ AI 分析（Admin のみ）にあり、3 つのプロバイダに対応し、同時にアクティブに できるのはちょうど 1 つです — フェイルオーバーの連鎖は意図的に持ちません。インシデントの データの送り先は、あなたが選んだちょうど 1 か所です。

プロバイダ	推論が実行される場所
Vertex AI（推奨）	自社の Google Cloud プロジェクトとリージョンの内部 — リクエストはすでに統制下にある境界の中に留まります
Google Gemini（直接 API）	Google のパブリック API — 運用上の境界の外へ出ます
Anthropic Claude（直接 API）	Anthropic のパブリック API — 運用上の境界の外へ出ます

各アダプタのエンドポイントホストは設定ではなくコード中の定数です — 設定ミスが、インシデントの データを気づかないうちに想定外のホストへ向け直すことはありません。Vertex では認証情報は任意です。 サービスアカウントキーを与えることも、省略して Google Cloud 上で動作するマシンのアンビエントな ID を使うこともできます。プロバイダの認証情報は、Yagra が保存する他のあらゆるシークレットと同じく 保存時にエンベロープ暗号で保護され、設定後に API から返されることはありません。

説明の依頼には Operator ロールが必要です（分析の実行と同じ、アラート確認（ACK）の権限です）。 生成の上限は分析ランナーとは独立に設けられています。

• 同時に実行できる生成は最大 2 件です（YAGRA_RCA_MAX_CONCURRENT）。
• リクエストは 1 分あたり最大 10 件です（YAGRA_RCA_RATE_PER_MIN）。
• レポートはインシデントの証拠をキーとして 15 分間キャッシュされます （YAGRA_RCA_CACHE_SECS）— 変化していない同じインシデントについて 2 度尋ねると、2 回目の推論 の費用を払う代わりにキャッシュから回答します。状況が動いたときのために再生成のオプションが キャッシュを迂回しますが、レート制限を迂回することはありません。
• 1 回の分析はツール呼び出し 6 ターン（YAGRA_RCA_MAX_TURNS）、実時間 240 秒 （YAGRA_RCA_TASK_BUDGET_SECS）、そしてツール出力の総量で上限が掛かります。上限に達した場合は リクエストを失敗させず、モデルの最後の回答を返します。YAGRA_RCA_MAX_TURNS=1 にすると v0.1.23 以前の単発動作に完全に戻ります — ツールは一切提示されず、プロバイダへ送られるリクエストは以前と バイト単位で同一です。

この調べもの（ルックアップ）は呼び出し元自身の可視範囲のもとで実行されます。グループスコープ を持つオペレーターの分析が、その人に見えないノードを読むことはできません。加えて閲覧専用の許可リストの下で 動きます — 書き込み系ツール、run_analysis、run_rca、監査ログはいずれも手が届かず、ツール単位 ではなく畳み込まれた分岐単位で検査されます。何を調べたかは回答と併せて保存され、WebUI と /mcp の双方で再生されます。証拠を常に添えてきたのと同じ理由です — 何に基づいたのか読み手が 確かめられない説明は、説明ではなく主張だからです。

設定 ▸ AI 分析には、設定したプロバイダへ最小限のリクエストを送る接続テストもあります。 おかげで「鍵は有効か、エンドポイントに到達できるか」は、インシデントの最中ではなく設定時に 答えが出ます。

プロバイダ側の失敗は上流のエラー（HTTP 502）として報告され、Yagra 自身の障害とは区別されます — おかげで「モデルが拒否した」と「Yagra が壊れた」が、Yagra 自身の監視の中で混同されることは ありません。

境界の外へ出るもの

運用データをモデルプロバイダへ送ることについては、正確な答えを示すべきです。以下がその答えです。

既定では何も送信されません。 プロバイダが設定されていなければ、この機能は不活性です — クライアントは存在せず、リクエストがシステムの外へ出ることもありません。データが外へ出るのは、 Admin がプロバイダを設定し、かつ Operator が明示的に説明を依頼したときだけです。

送信されるとき、プロンプトに含まれるものは次のとおりです。

• 根本原因となったノードの記述的な事実（名前、種別、アドレス、状態）。
• 説明の対象となるアラート — 何が、いつ、どのメトリクスやイベントで発生したのか。
• そのノードの依存関係のコンテキスト。名前つきの配下ノード最大 20 件と総数、そして上流の祖先の 連なり。
• インシデント前後のクロスシグナルなタイムライン — メトリクスの異常、パッシブイベント、フローの 変化。
• 監査ログからの直近の設定変更、最大 5 件。「何が変わったのか」が答えであることは多いからです。
• v0.1.23 以降は、モデルが呼び出した読み取り専用ツールの結果（例: あるインターフェースの トラフィック系列、ノードの状態、該当する syslog 行）。ここだけは事前に固定されていません — 何を取りに行くかはモデルが決めます（閲覧専用の許可リスト、呼び出し元の可視範囲、上記のターン・ 時間・出力量の上限の内側で）。レポートと併せて保存されるトランスクリプトが、何を取得したかの 正確な記録です。つまり何が出て行ったかは推測ではなく事後に監査できます。プロンプトを上記の固定 証拠だけに留めたい場合は YAGRA_RCA_MAX_TURNS=1 を設定してください。

決して送信されないもの: 監視の認証情報です — コンテキストは名前を指定したフィールドをコピー して組み立てられ、認証情報を持つ構造がそこへ到達し得ないことは、テストで固定しています。モデルが 使えるツールは読み取り専用で、保存されたシークレットを返すものはひとつもありません。機器の設定 本文は除外され、固定のコンテキストが運ぶのは依然としてインシデントのかたちであって生の エクスポートではありません — ただしツール呼び出しによって、特定のメトリクス系列やイベント集合を 必要に応じて引けるようになった点にはご注意ください（それがこの機能の目的です）。機器由来の テキスト（syslog のメッセージなど）は、最初のコンテキストで届いた場合もツールから返ってきた場合も 囲われ、信頼できないデータとして提示されます。おかげで敵対的なログ行は、指示ではなく証拠として 扱われます。

そしてそれは観測可能です。 モデルの呼び出しはすべて Yagra 自身の Prometheus メトリクスで 数えられます — 呼び出し回数、入出力のトークン数、エラー数を、プロバイダのラベル付きで。おかげで インシデントのデータがどれだけの頻度で、どれだけ外へ出ているのかは、信じるしかないものではなく、 グラフにもアラートにもできるものになります。

境界の要件が厳しいなら、推奨のかたちは Vertex AI プロバイダです。機能は同じまま、推論が自社の クラウドプロジェクトとリージョンの中で動きます。

AI クライアントから使う

このページのすべては、Yagra の MCP ツール経由でも到達できます。AI アシスタントは同じ 15 種類の分析を実行し（run_analysis）、長い実行をポーリングして分析結果を取得し、最近のジョブ を一覧できます — WebUI と同じ Operator 権限、同じ受付制御のもとで。 MCP サーバーを参照してください。