log-analysis

ログ分析

このスキルを使用する場面

• 主な作業が、コード変更や監視設計ではなく、読み取り専用のログトリアージである場合。
• ユーザーが、すべての行の言い換えではなく、最初に対処すべきブロッカーを求めている場合。
• 根拠となる情報が、アプリケーション、API、ワーカー、プロキシ、コンテナー、ポッド、ブラウザー、CI、または JSON のログである場合。
• 最初の失敗を特定した後、繰り返し現れるシグネチャーや影響範囲をまとめる必要がある場合。
• ユーザーが「トリアージ」と言っていなくても、実際の質問が**「どの行が重要か／本当のエラーは何か／連鎖的な障害はどこから始まるか」**である場合。

次の場合、このスキルを主なワークフローとして使用しないでください。

• ログがUnity／Unreal のビルド、クック、パッケージ、エディター、またはプレイヤーのログである場合 → game-build-log-triage を使用してください。
• 実際の作業が、計装、ダッシュボード、アラート、取り込み、保持、または可観測性のカバレッジである場合 → monitoring-observability を使用してください。
• ブロッカーがすでに判明しており、ユーザーが次に再現、仮説、または修正を必要としている場合 → debugging を使用してください。
• 主な作業が、最初の失敗のトリアージではなく、ログやテレメトリーファミリー全体にわたる繰り返し発生する異常やルールの探索である場合 → pattern-detection を使用してください。

基本理念

log-analysis は、巨大なトラブルシューティング百科事典ではなく、パケットルーターのように動作する必要があります。

1. リクエストを主要なログパケット 1 つに正規化します。
2. 解釈する前に、根拠となる情報の範囲を絞ります。
3. 最も早く対処可能な失敗を特定します。
4. 繰り返し発生する波及事象を、パターン／影響範囲のメモにまとめます。
5. 作業がデバッグ、可観測性設計、異常検出、またはエンジン専門のトリアージに移ったら、すぐに適切なワークフローへ引き継ぎます。

パケットを選択する前に、以下のサポートドキュメントを参照してください。

• references/intake-packets-and-route-outs.md
• references/triage-playbook.md
• references/source-boundaries.md

手順

ステップ 1：リクエストを正規化する

まず、プロンプトを次のインテーク形式に変換します。

log_analysis_packet:
  primary_packet: app-runtime | container-runtime | browser-plus-api | ci-cascade | structured-json | security-signal
  source_shape: app | proxy | worker | browser | ci | container | pod | json | mixed | unknown
  environment: local | ci | staging | production | browser | container | pod | unknown
  failure_goal: first-blocker | cascade-start | repeated-signature | blast-radius | suspicious-access | unknown
  anchor: timestamp | request-id | trace-id | job-build-id | browser-route | none | unknown
  route_after: stay-here | debugging | monitoring-observability | pattern-detection | game-build-log-triage

実行する主要パケットを1 つ選びます。2 つが同程度に適切と思われる場合は、不確実性を最も早く減らせる、より低コストのパケットを選んでください。

ステップ 2：パケットを選択する

パケット	使用する状況	特に適したケース	典型的な手掛かり
app-runtime	主な証拠がアプリ／API／ワーカー／プロキシのテキストログである	クラッシュ、スタックトレース、リクエストの失敗、キュー内の有害メッセージ	最初の致命的エラー行、ルート、サービス、リクエスト ID
container-runtime	証拠が docker logs、kubectl logs、ポッドの出力、またはデプロイ時間帯の再起動から得られる	コンテナのクラッシュ、環境変数／設定の不一致、依存関係への接続、再起動ループ	ポッド／コンテナ名、デプロイ時間帯、ホスト、リクエスト ID
browser-plus-api	ブラウザーのコンソール／ネットワーク上の症状を、サーバー側で確認する必要がある	401／403／500 のフロー、フェッチの失敗、CORS／認証の不一致、SSR とクライアントの不一致	ルート、リクエスト ID、タイムスタンプ、ブラウザー／ネットワークのトレース
ci-cascade	CI の出力に、最初のブロッカーの後で多くの二次的な失敗が含まれている	インストール／インポート／テスト／ビルドの連鎖、依存関係／設定の不足、ランナーの不一致	ジョブ名、ステップ名、ステージ、最初のスタックトレース／インポートエラー
structured-json	ログが JSON またはフィールドが豊富なイベントレコードである	エラーファミリーのグループ化、リクエスト／トレースの相関、ワーカー／イベントのトリアージ	レベル、サービス、リクエスト ID、トレース ID、テナント、イベント名
security-signal	アクセス／エラーログから、不審な探査や認証／権限の異常が疑われる	401／403／404 の繰り返しの探査、トークンの不正使用、レート制限の集中	IP／ユーザー／セッション、ルートの種類、ステータスコード、時間帯

パケットのルール：

• 通常のテキスト形式のスタックトレースやサーバーログには、app-runtime を優先します。
• 再起動のタイミング、ポッドの識別情報、または環境／デプロイの状況が重要な場合は、container-runtime を優先します。
• フロントエンドの症状だけでは十分でない場合は、browser-plus-api を優先します。
• 目に見える失敗が汎用的な中断ノイズである可能性がある場合は、ci-cascade を優先します。
• フィールドを使うと、自由形式のテキストを調べるよりグループ化や相関を効率よく行える場合は、structured-json を優先します。
• 不審なアクセス／認証の挙動が主な調査対象である場合に限り、security-signal を使用します。それ以外の場合は、セキュリティ関連に見えるノイズも、最初のブロッカーを扱うパケットに含めます。

ステップ 3：すべてを読む前に対象範囲を絞る

ログを解釈する前に、少なくとも 1 つの方法で対象を絞り込みます。

• 時間帯で絞り込む
• リクエスト／トレース／ジョブ／ビルド／セッション／テナントの識別子で絞り込む
• 致命的／対応が必要な行と、リトライやその後の影響を分ける
• ノイズの多い 1 つの発生元と、影響を受けた多数の発生元を分ける
• ブラウザーの症状を示す行と、サーバー側のブロッカーを示す行を分ける
• CI では、トランスクリプト全体を要約する前に、最初に失敗したステップを特定する

パケット別の有用なヒューリスティック：

• app-runtime → まず例外／致命的エラー／失敗／タイムアウト／拒否を確認する
• container-runtime → まず再起動時間帯と、依存関係／接続／環境設定の不一致を確認する
• browser-plus-api → 汎用的なクライアントの症状より先に、バックエンドの認証／設定／ランタイムの証拠を確認する
• ci-cascade → 中断／フッターの行より先に、最初のインポート／設定／ビルド／テストの失敗を確認する
• structured-json → 生の行を読む前に、メッセージの種類、例外クラス、リクエスト ID、またはサービスでグループ化する
• security-signal → エスカレーションする前に、広範な探査と単一のクライアントの不具合を区別する

ステップ 4：最初の対応可能な失敗を特定する

次の順序で確認します。

1. 致命的な停止 — クラッシュ、パニック、捕捉されない例外、プロセス終了、ビルド失敗
2. 依存関係／環境のブロッカー — 設定、シークレット、DNS、ファイル、サービス、認証、または接続の不足
3. リクエスト／ランタイムの失敗 — 500、タイムアウト、拒否されたプロミス、キュー内の有害メッセージ、パーサーの失敗
4. その後の影響 — リトライ、二次的な警告、繰り返されるヘルスチェックの失敗、広範な中断を示すテキスト

下流で繰り返される 20 行を、異なる 20 個の原因として報告しないでください。

ステップ 5：相関付けと分類

証拠が複数のソースにまたがる場合は、単に連結するのではなく相関付けを行います。

主な分類カテゴリ：

• missing-config-or-secret
• dependency-or-connection
• auth-or-permission
• request-or-runtime-error
• data-shape-or-validation
• resource-or-capacity
• browser-network-mismatch
• ci-build-test-failure
• security-or-suspicious-pattern
• unknown-needs-more-context

優先する相関付けの基準：

• タイムスタンプの範囲
• リクエスト／トレース／相関 ID
• ジョブ／ビルド ID または CI ステップ
• サービス／ワーカー／ポッド／コンテナー名
• ルート、ブラウザー操作、または API エンドポイント
• 安全に言及できる場合は、ユーザー／テナント／セッション識別子

ステップ 6：トリアージ概要を返す

デフォルトの回答形式：

# Log Triage

## Source
- Packet: app-runtime | container-runtime | browser-plus-api | ci-cascade | structured-json | security-signal
- Environment: local | CI | staging | production | browser | container | pod
- Confidence: high | medium | low

## First actionable failure
- Line or excerpt: `...`
- Why it matters: ...
- Why later lines look secondary: ...

## Pattern / blast radius
- Repeated signature: ...
- Scope: one request | repeated requests | one worker | one deploy window | one environment | broad

## Classification
- Primary bucket: ...
- Secondary bucket: ...

## Likely root cause
- 1-3 sentence explanation grounded in the evidence

## Next read-only checks
1. ...
2. ...
3. ...

## Route-out
- stay in `log-analysis` | `debugging` | `monitoring-observability` | `pattern-detection` | `game-build-log-triage`

ステップ 7：適切なタイミングで積極的に引き継ぐ

次の作業が最初の障害となったログのトリアージではなくなったら、切り替えます：

• 再現、仮説、コード／設定の修正 → debugging
• ダッシュボード、アラート、取り込み、テレメトリーの網羅性、保持期間 → monitoring-observability
• 多数の時間範囲やデータセットにわたる同一シグネチャの反復検出 → pattern-detection
• Unity／Unreal のビルド／エディター／パッケージのログ → game-build-log-triage

抜粋が短すぎる場合、または一連のエラーの途中から始まっている場合：

1. 確信度を低く設定します
2. 最も早いエラーのまとまり、または最初の障害の前後 20～80 行を提示するよう求めます
3. 必要な場合に限り、基準を 1 つ尋ねます：時間範囲、リクエスト ID、ジョブ／ビルド、ポッド／コンテナー、またはブラウザールート
4. 途中で切れた抜粋から確実だと装わないでください

例

例 1：コンテナーの依存関係エラー

プロンプト：

kubectl logs に Error: connect ECONNREFUSED redis:6379 と、その後に数十行の job retry failed が表示されています。

望ましい回答形式：

• container-runtime を選択します
• Redis 接続エラーを、最初に対処すべき障害として特定します
• 後続の再試行行を波及した結果としてまとめます
• 障害を切り分けた後に限り、次の対応先を debugging または monitoring-observability にします

例 2：ブラウザーと API の不一致

プロンプト：

ブラウザーコンソールには Failed to fetch と表示され、ネットワークタブでは /api/session が 401 を返し、サーバーログには JWT audience invalid と記録されています。

望ましい回答形式：

• browser-plus-api を選択します
• バックエンドの認証検証を、対処すべき障害として特定します
• ブラウザーのエラーは原因ではなく症状として扱います
• 設定／コードの疑わしい箇所が明確になった段階で、次の対応先を debugging にします

例 3：CI の連鎖エラー

プロンプト：

CI は test suite aborted で終了しますが、それ以前に ModuleNotFoundError: No module named 'dotenv' が記録されています。

望ましい回答形式：

• ci-cascade を選択します
• 最も早いインポートエラーを特定します
• 中断や末尾のメッセージは波及した結果として扱います
• 失敗している依存関係の経路が特定できた後に、次の対応先を debugging にします

例 4：自動化／Webhook の JSON ログ

プロンプト：

これらの JSON Webhook ログでは、1 回の invalid API key 応答の後に status=429 の再試行が繰り返されています。実際に重要なのは何ですか？

望ましい回答形式：

• 認証の不正利用が主な目的か、認証情報の誤り 1 件の調査が主な目的かに応じて、structured-json または security-signal を選択します
• 最初の認証情報／認証エラーを特定します
• 再試行の件数は分けて要約します
• ユーザーがより広範な異常調査を求めている場合に限り、繰り返しパターンの検出先を pattern-detection にします

ベストプラクティス

1. 質問に答えられる最小のパケットを選択します。
2. 最も目立つ行ではなく、最初の障害から説明します。
3. 繰り返される波及結果は、1 つのシグネチャまたは影響範囲の概要にまとめます。
4. 各ソースを個別に要約するのではなく、ブラウザー／ネットワーク／アプリケーションの証拠を相関付けます。
5. このスキル内で提案する確認は、すべて読み取り専用にします。
6. エンジン固有のログは、専門領域の明確な境界として扱います。
7. 作業がデバッグ、オブザーバビリティ設計、または異常検出に移った時点で、速やかに引き継ぎます。

参考資料

• references/intake-packets-and-route-outs.md
• references/triage-playbook.md
• references/source-boundaries.md