infrahub-collecting-diagnostics

Infrahub 診断情報コレクター

概要

Infrahub のユーザーから問題が報告されると、エキスパート （OpsMill サポート、またはシニアエンジニア）がトリアージを行うために、 ログ、設定、バージョン情報、環境の状態など、一貫したアーティファクト一式を必要とします。この スキルは、OpsMill 専用の診断バンドルツールである infrahub-collect を実行して、 そのアーティファクト一式を作成します。

このスキルは、バイナリの使い方を案内するものであり、手作りのコレクターではありません。根本原因を診断したり、 GitHub のイシューを起票したりすることはありません（その場合は infrahub-reporting-issues を使用してください）。また、Infrahub の状態を変更することもありません。infrahub-collect は読み取りのみを行います。

使用するタイミング

ユーザーが次のようなことを言った場合に、このスキルを起動します。

• 「Infrahub が壊れている／動かない／エラーが出る」
• 「デバッグを手伝ってほしい」
• 「OpsMill に送るログを収集したい」
• 「アップグレード後に何か問題が起きた」
• 「提案した変更が止まっている」
• 「UI で 500 エラーが発生している」

次の場合は起動しないでください。

• ユーザーが公開 GitHub イシューの起票を希望している （infrahub-reporting-issues を使用してください）
• ユーザーがデータに関する運用上の質問をしている （「サイト X にデバイスはいくつありますか」など） （infrahub-analyzing-data を使用してください）
• ユーザーがベストプラクティスに照らしてスキーマを監査したい （infrahub-auditing-repo を使用してください）

ワークフロー

次の手順を順番に実行してください。ユーザーの確認が必要なのは 2 か所です。 それ以外はすべて自動で行われます。

1. 問題の内容を確認する

まだ説明されていない場合は、問題を自分の言葉で説明するようユーザーに尋ねてください。まだ詳細を掘り下げる必要はありません。 製品名、バージョン番号、エラーメッセージ、ワークフローの状況に耳を傾けてください。これらは手順 4 で追加する create フラグの判断材料になります。

2. インストールして確認する

バイナリがすでに利用可能かどうかを確認します。

infrahub-collect version

見つからない場合は、ユーザーの OS／アーキテクチャ向けにインストールし、infrahub-collect version （または infrahub-collect --help）を使って再度確認してください。正確なインストールコマンド、sudo、エアギャップ環境に関する注意事項については、 rules/install-and-verify.md を参照してください。

3. 環境を検出する

infrahub-collect environment detect

検出結果が曖昧な場合（Compose プロジェクトが複数ある、 K8s の名前空間がデフォルト以外など）は、infrahub-collect environment list を実行し、 --project=<name> または --k8s-namespace=<ns> を使って特定してください。 Infrahub API トークンは不要です。このツールは既存の Docker／kubectl アクセスを再利用します。 rules/deployment-detection.md を参照してください。

4. バンドルを作成する

infrahub-collect create

手順 1 で確認した症状に合うフラグを追加します。 パフォーマンス問題や OOM の場合は --benchmark、 DB 操作の遅延や失敗には --include-queries、 サポートから再現用データを求められた場合は --include-backup を指定します。症状とフラグの完全な対応表については、 rules/create-flags.md を参照してください。

正常に動作していないデプロイでは、部分的なバンドルが作成されることがあります。create はその場合も終了コード 0 で終了し、収集に失敗した項目をマニフェストに記録します。そのままバンドルを送信してください。手作業で不足分を補おうとしないでください。

5. 共有前に確認する（ユーザー確認が必要）

infrahub-collect がマスクするのは、一般的な秘密情報のキー名（password／secret／token／key → ********）のみです。ログやクエリの内容、またはその他のキー名で保存された秘密情報は除去されません。 ユーザーと一緒に bundle/logs/ と bundle/server/ を確認し、ホスト名、IP アドレス、顧客データ、標準以外のキー名で保存された秘密情報が含まれていないかを確認してから、共有について明示的な同意を得てください。rules/review-before-sharing.md を参照してください。

6. 共有／引き継ぎ

ユーザーがバンドルを安全に共有できると確認したら、サポート窓口（Discord、Slack、メール）を通じて送信します。ユーザーが公開 GitHub イシューの起票も希望する場合は、infrahub-reporting-issues に引き継いでください。詳細は rules/cross-link-reporting-issues.md を参照してください。 エキスパートへの引き継ぎの前、またはその代わりに、バンドルをローカルで一次分析（トレースバック、失敗、既知の問題との照合）したい場合は、infrahub-analyzing-diagnostics に進んでください。このスキルは収集のみを行い、トリアージは分析スキルが担当します。

ルールのカテゴリ

プレフィックス	カテゴリ	説明
workflow	ワークフロー	ユーザーゲートのセマンティクス、ステップの順序
install	インストール	infrahub-collect バイナリの検証/インストール
deployment	検出	environment detect/list に委ねる
create	create フラグ	create の症状からフラグへのマッピング
collection	収集	読み取り専用ツール、変更なし
bundle	バンドル	ディスク上の bundle/ レイアウト（リファレンス）
review	レビュー	キー名マスキングのギャップ、共有前のユーザーレビュー
cross-link	クロスリンク	infrahub-reporting-issues への引き継ぎ

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

補足リファレンス

• reference.md — 完全なフラグリファレンス、 バンドルレイアウトの詳細、および環境変数に関する 注記。ステップ 2〜4 で参照します。
• examples.md — 一般的な症状クラス向けの エンドツーエンドのウォークスルー。
• ../infrahub-common/rules/workflow-information-priority.md -- スキルコンテンツを優先。真のギャップ（例: ノードの削除）が ある場合に docs.infrahub.app を参照する方法

アンチパターン

• 状態を変更するものを実行すること。 docker compose down や kubectl delete は禁止です。 infrahub-collect は設計上読み取り専用であり、 そうでないコマンドを追加しないでください。
• バイナリを使わずに収集を自作すること。 手動での docker compose logs / kubectl logs のスクリプト化は禁止です — infrahub-collect create はすべてのサービス、レプリカ、 ログローテーションをすでにカバーしています。
• 共有前レビューゲートを省略すること。 ツールのマスキングは キー名ベースのみであり、この特定のユーザーにとって何が 機密であるかは判断できません。バンドルの共有を承認できるのは ユーザーだけです。
• 根本原因を断定すること。 このスキルは専門家がトリアージするための バンドルを生成するものであり、診断ではありません。 何を収集したかを述べ、結論は専門家に委ねてください。
• このスキルから GitHub Issue を起票すること。 それは infrahub-reporting-issues の役割です。重複させず、 クロスリンクしてください。