infrahub-analyzing-diagnostics

Infrahub 診断アナライザー

概要

infrahub-collecting-diagnostics はバンドルを生成します。 このスキルはその次のステップで、バンドルを読み込み、 未加工のログをトリアージレポートにまとめます。bundle_information.json を解析し、 各サービスのログ全体からエラーの兆候（トレースバック、ERROR／CRITICAL 行、パニック、OOM キル、再起動の証拠）を探し、 関連するエラーをインシデントとして関連付けます。また、 既存の opsmill/infrahub GitHub イシューを検索し、 誰かがイシューを登録する前に、クラッシュがすでに 把握されている問題かどうかをユーザーが確認できるようにします。

出力はバンドル内の証拠に基づく調査結果レポートであり、 修正ではありません。このスキルはデプロイ環境に対して 厳密に読み取り専用です。すでに収集済みのバンドルから ファイルを読み取り、GitHub 検索を実行しますが、 稼働中の Infrahub インスタンスには触れず、修復措置も 適用しません。

使用するタイミング

次のようなユーザーの発言があった場合に、このスキルを 実行します。

• 「バンドルを収集しました。何が問題なのか教えてもらえますか？」
• 「これらの Infrahub ログ／このバンドルを分析してください」
• 「バンドル内のトレースバックは何を意味していますか？」
• 「このクラッシュは既知の Infrahub の問題ですか？」
• 「task-worker が再起動を繰り返したのはなぜですか？」

次の場合は実行しないでください。

• バンドルがまだない場合 — まず収集するように infrahub-collecting-diagnostics に引き継いでください。 ここで独自にログを収集してはいけません。
• ユーザーがバグや機能リクエストの登録を希望している場合 （infrahub-reporting-issues を使用してください）
• ユーザーが稼働中のデータについて運用上の質問をしている場合 （infrahub-analyzing-data を使用してください）

ワークフロー

次の手順を順番に実行します。

1. バンドルの場所を尋ねる（ユーザーへの確認）

バンドルの場所をユーザーに尋ねてください。ファイルシステムを 検索して見つけたり、コレクターのデフォルト出力 ディレクトリにあると仮定したりしてはいけません。1 台のマシンに 複数のバンドルが存在することはよくあり、間違ったものを選ぶと、 別のインシデントについて確信に満ちたレポートを出すことに なります。ヒントとしてデフォルトの場所に言及するのは構いません （--output-dir が設定されていない場合は ./infrahub_bundles/）が、パスはユーザーに指定してもらいます。 ユーザーがすでにパスを示している場合、またはバンドルの内容を 貼り付けている場合に限り、質問を省略します。パスが示されたら、 bundle_information.json を含む bundle/ ディレクトリがある infrahub-collect バンドルのように見えることを確認します。 バンドルがまったくない場合は処理を中止し、 infrahub-collecting-diagnostics に引き継いでください。 代わりに docker compose logs／kubectl logs を取得しては いけません。 こちらを参照してください。

2. まずマニフェストを読み、次にデプロイ環境のコンテキストを確認する

ログを開く前に bundle/bundle_information.json を読みます。 ここには、収集した内容、失敗した処理、対象のデプロイ環境が 記録されています。収集の失敗自体も調査結果になります。 ログを収集できなかったサービスが、停止しているサービスである こともよくあります。 rules/workflow-manifest-first.mdを参照してください。

次に、デプロイ環境のコンテキスト（稼働中の Infrahub のバージョン、 トポロジー（Compose または Kubernetes）、レプリカ数）を確認し、 その内容を冒頭に記載してレポートを作成します。バージョンが わかれば、後で一致した GitHub イシューを結論につなげられます （「X.Y.Z ですでに修正済み — アップグレードしてください」か、 「修正版がすでに稼働中 — リグレッションの可能性あり」か）。 rules/workflow-deployment-context.mdを参照してください。

3. エラーシグナルを調査する

bundle/logs/ 配下のすべてのサービスディレクトリをスキャンします。サーバーだけではありません。rules/triage-error-signals.md に記載されているシグナルの種類、つまり Python のトレースバック、ERROR／CRITICAL のログ行、パニック、OOM による強制終了、接続失敗を調べます。*.previous.log ファイルは再起動の証拠として扱い、その末尾を読みます。通常、再起動前のログにクラッシュの原因が記録されています （rules/triage-restart-evidence.md）。 reference.md には、シグナルの種類ごとにすぐ使える grep パターンが記載されています。

マニフェストにベンチマークが収集されたと記載されている場合（create --benchmark）、ログと併せて評価します。単一 CPU のスコアと Neo4j／PostgreSQL ボリュームのストレージ IOPS は、速度低下の症状がソフトウェアの問題なのか、ホストのスペック不足なのかを判断する決め手になることがよくあります。ベンチマークがなく、症状がパフォーマンスに関係する場合は、次回のバンドルで --benchmark を指定するようレポートで推奨する必要があります。rules/triage-benchmark-results.md を参照してください。

4. インシデントとして関連付ける

生のシグナルを、タイムスタンプと因果関係に基づいてインシデントにまとめます。根本原因となるエラーと、下流サービスで発生する連鎖エラーを区別し、根底にある問題ごとに1件のインシデントとして扱います。14:02 のデータベースの OOM に続いて14:02以降にサーバーの接続エラーが発生している場合、これは2件ではなく1件のインシデントです。rules/correlate-into-incidents.md を参照してください。

5. 既存の GitHub issue と照合する

トレースバックまたは特徴的なエラーメッセージで裏付けられた各インシデントについて、安定した要素（例外クラス、正規化したメッセージ、最も内側にある Infrahub フレーム。変動する ID、ブランチ名、ホスト名は除外）から検索キーを作成し、次を検索します。

gh search issues --repo opsmill/infrahub "<stable keywords>"

デフォルトの検索対象にはオープンとクローズの両方の issue が含まれます。片方が検索対象から外れるため、--state は指定しないでください。

上位の一致候補を、タイトル、状態、URL とともに提示します。gh search issues が返す情報はこれだけです。修正されたバージョンは出力に含まれないため、有望な候補を開き、ステップ2で確認したデプロイ環境と照らし合わせます。issue にバージョンの記載がない場合はその旨を伝え、アップグレードが必要かどうかは未確定のままにします。キーの作成方法と gh を利用できない場合の代替手段については rules/match-stable-search-keys.md を参照してください。また、一致候補の内容を読むコマンドと、検索前に確認すべき既知の障害パターンについては reference.md を参照してください。よくある症状のいくつかは原因がよく知られているため、汎用的な検索ではなく、対象を絞った検索が可能です。

6. 調査結果を報告する

調査結果のレポートを作成します。インシデントごとに1つのセクションを設け、重大度、証拠（バンドル内のファイルパスと引用した抜粋）、関連付けの根拠、該当する GitHub issue を記載します。すべての主張は、引用したバンドル内の行までたどれる必要があります。不明な点は不明として記載します （rules/report-evidence-per-finding.md）。 未解決の質問には、症状が要求に応じて再現するか、最後に再現したのはいつかを含めます。再現した時刻が分かるとインシデントの時間範囲を絞り込め、次回のバンドルで何を収集すべきかも明確になります。 レポートでは次の手順を提案しますが、実行はしません。再起動や設定変更は行いません （rules/scope-read-only-analysis.md）。

7. 引き継ぐ

調査結果に応じて、適切な引き継ぎ先を案内します。

• 該当するオープンな GitHub issue がある → ユーザーにその issue を案内します。再現情報をコメントする場合は infrahub-reporting-issues を利用します。
• 該当する issue がなく、ユーザーが起票を希望する → infrahub-reporting-issues に引き継ぎます。このスキルから gh issue create を実行してはいけません。
• より詳しい専門家の支援が必要 → バンドルとこのレポートを OpsMill サポートに送ります。その際は infrahub-collecting-diagnostics の共有前レビューのゲートに従います。調査結果から再現手順の作成が必要と考えられる場合は、まず最小限の再現可能な例を提案します。フルバックアップ（--include-backup）は最後の手段であり、デフォルトで求めるものではありません。

rules/cross-link-skill-boundaries.md を参照してください。

ルールのカテゴリ

プレフィックス	カテゴリ	説明
workflow	ワークフロー	まずマニフェストを確認し、収集の失敗も検出事項として扱います
triage	トリアージ	エラーシグナルの分類、すべてのサービス、再起動の証拠
correlate	相関分析	シグナルをインシデントにまとめ、根本原因と連鎖的な影響を区別します
match	イシューの照合	opsmill/infrahub のイシューに対する安定した検索キー
report	報告	検出事項ごとに証拠を提示し、不明な点は不明のままにします
scope	スコープ	分析のみ。変更や修正は行いません
cross-link	相互リンク	関連するスキルへの引き継ぎ

全体のインデックスについては、rules/_sections.md を参照してください。

参考資料

• reference.md — シグナル分類別の grep パターン、サービスごとのログ形式、マニフェストのフィールド、 gh search の使用例です。手順 3～5 で読みます。
• examples.md — エンドツーエンドの例： バンドルの抜粋を入力し、検出事項のレポートを出力します。
• ../infrahub-collecting-diagnostics/reference.md — infrahub-collect が生成するバンドルのレイアウトに関する 正式な資料です。
• ../infrahub-common/rules/workflow-information-priority.md -- スキルの内容を優先し、真に情報が不足している場合に docs.infrahub.app を参照する方法を説明します。

アンチパターン

• バンドルの場所を推測する。 ファイルシステムを スキャンしたり、「最も新しいディレクトリを選ぶ」、 ./infrahub_bundles/ にあると決めつけたりしてはいけません。 ユーザーにパスを確認してください。
• 証拠なしで診断する。 検出事項にはすべて バンドルのパスと引用した抜粋を記載します。ログ行で裏付けられない もっともらしい説明は推測であり、推測だと明記する必要があります。
• エラーの一覧をそのまま報告する。 1 件のデータベース OOM に 起因する下流の 50 件の接続エラーは、1 件のインシデントです。 報告する前に相関分析を行ってください。
• 変動しやすいトークンで GitHub を検索する。 ブランチ名、 UUID、ホスト名、タイムスタンプを含めると、検索結果が 返ってこないことがあります。これらを取り除き、安定した部分で 検索してください。
• 分析ではなく修正を行う。 再起動、docker／kubectl による 変更、設定ファイルの編集は禁止です。推奨事項はレポートに記載し、 対応はユーザーまたは OpsMill サポートに委ねます。
• このスキルから GitHub イシューを作成する。 その作業は infrahub-reporting-issues が担当します。ルーティングとサニタイズを 重複させず、相互リンクしてください。
• バンドルが不完全な場合に手作業で再収集する。 デプロイが 劣化している場合、バンドルが一部のみなのは想定内です。マニフェストに 欠落が記録されています。追加データが本当に必要な場合は、 infrahub-collecting-diagnostics に引き継いでください。