eks-app-log-analysis

EKS アプリケーションログ分析

FIS の障害注入実験中に EKS アプリケーションログを分析し、インフラストラクチャ障害に対するアプリケーションの応答を把握します。リアルタイム監視モードと事後分析モードに対応しています。

出力言語ルール

ユーザーとの会話の言語を検出し、すべての出力で同じ言語を使用します。

• 中国語の入力 → 中国語の出力
• 英語の入力 → 英語の出力

前提条件

必要なツール：

• kubectl — 対象の EKS クラスターへのアクセスが設定されていること
• AWS CLI — FIS 実験のステータスの照会に使用します
• 準備または実行済みの FIS 実験ディレクトリ（aws-fis-experiment-prepare または aws-fis-experiment-execute から取得）

ワークフロー

digraph log_analysis_flow {
    "Receive input path" [shape=box];
    "Detect mode" [shape=diamond];
    "Real-time mode" [shape=box];
    "Post-hoc mode" [shape=box];
    "Read service list" [shape=box];
    "Auto-discover + confirm app dependencies" [shape=box];
    "Start background log collection" [shape=box];
    "Batch fetch historical logs" [shape=box];
    "Frontend polling + insight display" [shape=box];
    "Experiment complete?" [shape=diamond];
    "Generate analysis report" [shape=box];

    "Receive input path" -> "Detect mode";
    "Detect mode" -> "Real-time mode" [label="directory with README"];
    "Detect mode" -> "Post-hoc mode" [label="*-experiment-results.md"];
    "Real-time mode" -> "Read service list";
    "Post-hoc mode" -> "Read service list";
    "Read service list" -> "Auto-discover + confirm app dependencies";
    "Auto-discover + confirm app dependencies" -> "Start background log collection" [label="real-time"];
    "Auto-discover + confirm app dependencies" -> "Batch fetch historical logs" [label="post-hoc"];
    "Start background log collection" -> "Frontend polling + insight display";
    "Frontend polling + insight display" -> "Experiment complete?";
    "Experiment complete?" -> "Frontend polling + insight display" [label="No, continue"];
    "Experiment complete?" -> "Generate analysis report" [label="Yes"];
    "Batch fetch historical logs" -> "Generate analysis report";
}

ステップ 1：モードの判定とコンテキストの読み込み

ユーザーは次のいずれかを指定します。

• ディレクトリパス（例：./2026-03-31-14-30-22-az-power-interruption-my-cluster/）→ リアルタイムモード
• レポートファイルのパス（例：./2026-03-31-...-experiment-results.md）→ 事後分析モード

リアルタイムモード： ディレクトリには、準備スキルが生成した README.md が含まれています。 そこから実験テンプレート ID とリージョンを抽出します。

事後分析モード： ファイルは実験結果レポートです（「FIS Experiment Results」を含みます）。そこから実験 ID、開始時刻、終了時刻、リージョンを抽出します。

ステップ 2：サービス一覧の読み込み

影響を受ける AWS サービスを、次のいずれかから抽出します。

• 実験ディレクトリの expected-behavior.md（リアルタイムモード）、または
• 実験結果レポート（事後分析モード）

サービス名の見出し（例：「### RDS (cluster-xxx)」）を探して一覧を作成します。 検出したサービス一覧をユーザーに提示します。

ステップ 3：アプリケーションの依存関係の収集

3a. 依存関係の候補を自動検出する

影響を受ける AWS サービスごとに、そのサービスに依存している可能性のある EKS アプリケーションを自動的に検出します。

1. AWS CLI を使用してサービスのエンドポイント（例：RDS クラスターのエンドポイント、ElastiCache のプライマリエンドポイント、EC2 のプライベート IP/DNS）を取得します
2. すべての名前空間の Pod 環境変数を検索し、そのエンドポイントへの参照を探します
3. すべての名前空間の ConfigMap を検索し、そのエンドポイントへの参照を探します
4. 検出した namespace/deployment の候補と、照合箇所（環境変数名、ConfigMap 名）をユーザーに提示します

3b. ユーザーによる確認と手動での追加

自動検出された依存関係をユーザーに確認し、見落とした依存関係があれば追加してもらいます。最終的な対応関係を SERVICE_APP_MAP（サービス → namespace/deployment のペアの一覧）として保存します。

ステップ 4：ログの収集

シェルスクリプトのルール： 複数行のスクリプトを使用します。1 行で && を使ってコマンドを連結しないでください — バックグラウンドの & プロセスの後に変数が失われます。

すべてのログを一時ディレクトリ /tmp/{timestamp}-fis-app-logs/ に保存し、サービス名のサブディレクトリごとに整理します。

リアルタイムモード：バックグラウンド収集

SERVICE_APP_MAP 内の各アプリケーションについて、通常のコンテナのみ（FIS が挿入したエフェメラルコンテナを除く）を対象に、バックグラウンドの kubectl logs -f プロセスを開始します。

1. .spec.selector.matchLabels から Deployment の Pod ラベルセレクターを特定します
2. Deployment の仕様から通常のコンテナ名の一覧を取得します。

   kubectl get deployment {DEPLOYMENT} -n {NAMESPACE} \
     -o jsonpath='{.spec.template.spec.containers[*].name}'
   

   --all-containers=true は使用しないでください — FIS の Pod レベルの障害注入（例： pod-network-latency、pod-cpu-stress）では、対象の Pod にエフェメラルコンテナが挿入されます。--all-containers を使用すると、アプリケーションログと一緒に FIS エージェントのログ（ノイズ）も取得してしまいます。通常のコンテナのみを収集するには、必ず --container={name} を使用してください。
3. 通常のコンテナごとに、バックグラウンドのログストリームを開始します。

   kubectl logs -f --selector={labels} -n {NAMESPACE} \
     --container={CONTAINER_NAME} --timestamps --prefix=true \
     --max-log-requests=20 \
     >> {LOG_DIR}/{service-name}/{deployment}.log &
   

   --selector={labels}（deployment/xxx ではなく）を使用します — これにより、実験中に再作成された Pod を含め、一致するすべての Pod のログを取得できます。
4. 各バックグラウンド PID を {LOG_DIR}/.pids に記録し、クリーンアップに備えます

事後モード：一括取得

事後モードでは、実験中にポッドが終了している場合があります。まず Container Insights が利用可能かを確認し、ログソースを選択します。

Step 4a：Container Insights の検出

EKS クラスターで Container Insights が有効になっているか確認します。

• amazon-cloudwatch-observability EKS アドオンを確認します（aws eks describe-addon を使用）
• または、amazon-cloudwatch 名前空間内の CloudWatch エージェント／Fluent Bit デーモンセットを確認します

Step 4b：CloudWatch Logs（Container Insights が有効な場合に優先）

ロググループ /aws/containerinsights/{CLUSTER_NAME}/application に対して、実験時間帯 （START_TIME から END_TIME）の CloudWatch Logs Insights クエリを実行します。各デプロイメントについて、kubernetes.namespace_name と kubernetes.labels.app（またはポッド名のパターン）でフィルタリングします。これにより、現在は存在しないポッドのログも含め、完全なログを取得できます。

Step 4c：kubectl logs（フォールバック、Container Insights がない場合）

各通常コンテナーについて、kubectl logs --selector={labels} --since-time={START_TIME} を --container={CONTAINER_NAME} --timestamps --prefix=true とともに使用します （コンテナーの検出方法は、リアルタイムモードの Step 2 と同じです）。--all-containers は使用しないでください。 注：現在実行中のポッドのログのみを取得します。実験中に終了したポッドのログは失われます。

Step 5：リアルタイム監視の表示

実験の実行中は、30 秒ごとにポーリングします。各サービスグループおよび各アプリケーションについて、次の処理を行います。

1. ログファイルから、収集済みログの直近 30 秒分を読み取ります
2. エラーレベルのエントリー（error、exception、fail、refused、timeout に一致）と、警告レベルのエントリー（warn、retry に一致）を数えます
3. アプリごとの概要を表示します：エラー数、警告数、直近 5 件のエラー行
4. 最近の行から復旧の兆候（connected、restored、success、recovered）を検出し、見つかった場合は報告します

Step 6：実験ステータスの確認（リアルタイムモード）

aws fis list-experiments を使用して、一致するテンプレート ID の実験が引き続き running 状態かどうかを確認します。実験が完了した場合（または見つからない場合）は、レポートの生成に進みます。

Step 7：分析レポートの生成

実験完了後（または事後モードの場合は直ちに）、レポートを生成します。

TIMESTAMP=$(date +%Y-%m-%d-%H-%M-%S)
# Save the report in the experiment directory (EXPERIMENT_DIR)
REPORT_FILE="${EXPERIMENT_DIR}/${TIMESTAMP}-app-log-analysis.md"

レポートの構成：

# Application Log Analysis Report

**Experiment ID:** {EXPERIMENT_ID}
**Analysis Time:** {TIMESTAMP}
**Time Range:** {START_TIME} - {END_TIME}
**Duration:** {DURATION}

## Summary

| Service | Application | Total Errors | Peak Error Rate | Recovery Time |
|---------|-------------|--------------|-----------------|---------------|
| {service} | {app} | {count} | {rate}/min | {time} |

## Per-Service Application Analysis

### {Service Name} ({resource_id})

#### {Application Name} ({namespace}/{deployment})

**Error Timeline:**

| Time (UTC) | Level | Message |
|------------|-------|---------|
| {HH:MM:SS} | ERROR | {truncated message} |
| ... | ... | ... |

**Key Error Patterns:**

| Pattern | Count | First Occurrence | Last Occurrence |
|---------|-------|------------------|-----------------|
| Connection refused | {n} | {time} | {time} |
| Timeout | {n} | {time} | {time} |

**Log Sample (Critical Errors):**

{実際のエラーログを5～10行}

**Insights:**
- {insight_1}: Error spike at {time}, correlates with {service} failover
- {insight_2}: Recovery detected at {time}, {duration} after fault injection ended
- {insight_3}: Application retry mechanism worked/failed because...

(Repeat for each application)

## Cross-Service Correlation

| Time | Event | RDS Impact | ElastiCache Impact | Application Response |
|------|-------|------------|--------------------|--------------------|
| {time} | Fault injection start | - | - | First errors appear |
| {time} | {service} failover | Connection errors | - | Retrying... |
| {time} | Recovery | Connections restored | - | Normal operation |

## Recommendations

1. **{Issue}:** {description}
   - **Impact:** {what happened}
   - **Recommendation:** {what to improve}

## Appendix: Log File Locations

**Raw log directory:** `{LOG_DIR}`

To view raw logs after the analysis, navigate to the temp directory shown above.
These files will persist until the system clears `/tmp`.

| Application | Log File |
|-------------|----------|
| {app} | `{LOG_DIR}/{service}/{app}.log` |

Step 8：クリーンアップ（リアルタイムモード）

{LOG_DIR}/.pids に記録されたバックグラウンドの kubectl logs プロセスをすべて終了します。 クリーンアップ後、PID ファイルを削除します。

エラー処理

エラー	原因	解決方法
/.pids: Permission denied	&& チェーンが原因で LOG_DIR 変数が空になり、パスが /.pids に解決される	複数行のスクリプトで export LOG_DIR=... を使用し、&& チェーンは使用しないでください。Step 4 の注記を参照してください。
kubectl: command not found	kubectl がインストールされていない	kubectl をインストールし、kubeconfig を設定します
error: You must be logged in	kubeconfig が設定されていない	aws eks update-kubeconfig --name {cluster} を実行します
No resources found	デプロイメント／ポッドが存在しない	デプロイメント名と名前空間を確認します
Unable to retrieve logs	ポッドが実行されていないか、再起動された	ポッドのステータスを確認します。CloudWatch Logs からの取得が必要な場合があります
Template ID not found	README の形式が変更された	テンプレート ID を手動で指定します

出力ファイル

{EXPERIMENT_DIR}/                                 # Experiment directory
└── {timestamp}-app-log-analysis.md               # Analysis report

/tmp/{timestamp}-fis-app-logs/                    # Temp directory for raw logs
├── rds-cluster-xxx/
│   ├── app-backend.log
│   └── api-server.log
├── elasticache-redis-xxx/
│   └── cache-layer.log
└── .pids (temporary, cleaned up)

使用例

# Real-time monitoring (during experiment)
"Analyze app logs for ./2026-03-31-14-30-22-az-power-interruption-my-cluster/"
"Monitor application behavior in the experiment directory"
"实时监控应用日志"

# Post-hoc analysis (after experiment)
"Analyze app logs using ./2026-03-31-14-35-00-az-power-interruption-my-cluster-experiment-results.md"
"分析实验报告中的应用表现"
"Check what happened to applications during the experiment"

他のスキルとの連携

• aws-fis-experiment-prepare — コンテキストとして README.md と expected-behavior.md を読み取ります
• aws-fis-experiment-execute — 時間範囲とサービスリストを取得するために *-experiment-results.md を読み取ります
• 他のスキルのファイルは変更しません