トラブルシュートと AI RCA

監視は、何かがおかしいということを教えてくれます。Troubleshoot のセクションは、その次の問い のためにあります。何がおかしいのか、そしてなぜか、です。

用意されているものは 2 つです。Yagra がすでに集めたデータを掘り下げるオンデマンド分析のカタログと、 インシデントの証拠を文章による根本原因の説明に変える AI のレイヤー（自分で選んで有効にします）です。

オンデマンド分析

トラブルシュートの分析は、Yagra 自身のストアを読むだけのジョブです。読む先は、メトリクスの 時系列データベース、パッシブイベントのログストア、トラフィックフローのストアです。

機器には一切触れません。追加のポーリングもしませんし、設定も読みませんし、調べているネットワーク へトラフィックを出すこともありません。ですから分析は、インシデントの真っ最中でも安全に実行できます。 そしてまさに、実行したいのはその瞬間です。

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

• 範囲 — all（インベントリ全体）、group（1 つのグループの直接のメンバー）、node （1 台のノード）。

  範囲を選ぶ画面は、サーバー側でフリートを検索します。ですから数万台から 1 台を見つける操作は、 スクロールではなく入力です。

• 深さ — ジョブが調べるノードの数です。quick は 20 ノード、standard（既定）は 60 ノードに 絞ります。exhaustive は上限を上げ、フリート全体を覆えるようにします。

  深く調べるほど時間がかかります。quick は、最初の一手が数秒で返ってくるためにあります。

• 細かい調整 — ほとんどのツールは、対象の期間、比べる相手の期間、感度の設定を受け付けます。 メトリクス系のツールでは、調べるメトリクスの種類も絞れます（到達性とインターフェースだけ、 あるいはシステムのメトリクスだけ）。

  「この 1 時間を直近 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 クライアントのせいで、人が起動した分析が後回しになることはありません。AI の 側も同じ 429 に当たります。MCP から起動した分析は、実行したトークンの識別情報とともに監査ログにも 残ります。

結果の読み方

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

「専用」が何を意味するのか、例を 3 つ挙げます。

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

分析の結果からは、対象のノードへリンクで戻れます。どのレポートも CSV でエクスポートできます。 そしてそれぞれに、共有できるリンク（?job=）があります。

インシデント対応のチャンネルに貼れば、同僚は説明ではなく同じレポートそのものを開きます。この リンクはジョブを直接指すので、最近の一覧から流れてしまった実行へのリンクでも開けます。間違った ツールの下に貼られたリンクは、実際にそれを読めるレポートへ自動で移ります。

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

検出結果を横断して探す

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

トラブルシュート ▸ 保存済み分析結果は、すべての実行を横断して、見つかったものを新しい順に検索 します。絞り込みは、ノードやサイト、分析の種別、重大度、期間で行えます。

各行は、それを見つけた実行のレポートへリンクします。ですから気になる 1 件から、その全体像までは 1 クリックです。一覧はキーセットページングを使うので、運用期間がどれだけ長くなっても実用に耐え ます。

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

誰も見ていなくても回しておきたい分析があります。夜間の異常検知や、週次のキャパシティ予測などです。

トラブルシュート ▸ 定期実行は、毎日・毎週・毎月の指定した時刻（UTC）に分析を実行します。対象は フリート全体、1 つのサイト、1 台のノードから選べます。期間や感度の設定は、手動実行と同じです。

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

• 拒否された発火は、飛ばすのではなく先送りします。 スケジュールの時刻に入場の制御が満杯だった 場合、その回は起動しません。しかしスケジュールは「実行すべき」状態のまま残り、1 分後のタイミング で再試行します。

  ですから混雑した一瞬が奪うのは 1 分であって、1 周期まるごとではありません。一覧では、その試行を 「延期」として表示し、失敗とは区別します。

• フローストアの無い環境では、トラフィックフロー系の分析をスケジュールできません。 ClickHouse を設定していない場合、フローの分析は「フロー層が有効ではありません」という 1 行を返します。

  1 度きりの問いへの答えとしては、それで妥当です。しかし毎晩問い続ければ、空の実行が積み上がる だけです。ですからスケジュールの選択肢には出しませんし、API も拒否します。

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

AI による根本原因分析

分析群の上には、AI のレイヤーが乗ります（自分で選んで有効にします）。LLM が、Yagra 自身のデータ に基づいて、インシデントの根本原因の説明を書きます。

使い方はこうです。アクティブアラートの画面から、Operator が Yagra に「このインシデントを説明して」 と依頼します。

すると Yagra は証拠を組み立てます。アラート、影響を受けたノードの事実、依存関係グラフ上でのその 位置、障害の前後にわたる複数の信号のタイムラインです。それを設定したモデルへ送り、構造化された 回答を受け取ります。

回答に含まれるのは、要約、推定される根本原因、影響を受ける配下のノード、次に取るべき手順の提案、 そして確からしさの見積りです。

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

• 説明するのは根本原因であって、クリックした症状ではありません。 起点にしたアラートが、親の 障害の下で抑制されている子だった場合、説明の対象は親になります。アラートパイプラインがすでに 計算している、あの根本原因のまとめと同じです（アラートを 見てください）。

• 根拠は Yagra がすでに持っている証拠で、モデルは自分でも取りに行けます。 モデルはインシデント の文脈から出発します。そして v0.1.23 以降は、Yagra の読み取り専用 MCP ツール を通じて自分で調べられます。

  たとえば、インターフェースの推移を引く、そもそもポーラーが生きていたか確かめる、syslog に何が 出ていたか読む、発火したしきい値を見る、といったことです。

  以前は決まった事実を渡されて一発で答える形でした。ですから、あらかじめ含めると決めたものに ついてしか考えられませんでした。なお、モデル自身がネットワークにつなぐ能力や、機器に触れる能力は、 今もありません。

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 回の分析には 3 つの上限があります。ツール呼び出し 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 を設定してください。

決して送信されないもの: 監視の認証情報です。

文脈は、名前を指定したフィールドをコピーして組み立てます。認証情報を持つ構造がそこへ入り込めない ことは、テストで固定しています。モデルが使えるツールは読み取り専用で、保存されたシークレットを 返すものは 1 つもありません。

機器の設定そのものも除外します。固定で送る文脈が運ぶのは、あくまでインシデントのかたちであって、 生のエクスポートではありません。

ただし 1 つ注意があります。ツール呼び出しによって、特定のメトリクスの推移やイベントの集合を、 必要に応じて引けるようになりました。それがこの機能の目的です。

機器から来たテキスト（syslog のメッセージなど）は、最初の文脈で届いた場合も、ツールから返ってきた 場合も、囲って「信頼できないデータ」として提示します。おかげで悪意あるログの行は、指示ではなく 証拠として扱われます。

そしてこれは、外から観測できます。 モデルの呼び出しは、すべて Yagra 自身の Prometheus メトリクスで数えます。呼び出し回数、入出力のトークン数、エラー数を、プロバイダのラベル付きで 記録します。

ですからインシデントのデータがどれだけの頻度で、どれだけ外へ出ているかは、信じるしかないもので はありません。グラフにもアラートにもできます。

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

AI クライアントから使う

このページの内容はすべて、Yagra の MCP ツール経由でも使えます。AI のアシスタントは、同じ 15 種類の 分析を実行し（run_analysis）、長い実行の結果を取りに行き、最近のジョブを一覧できます。権限は WebUI と同じ Operator で、入場の制御も同じです。 MCP サーバーを参照してください。