v1.8.1 — アラートトリガー AI 診断 + ドキュメント大幅拡充

2026年4月23日 · 約8分で読めます

外部アラートシステムのイベントを受信し、相関分析 → 自動 AI 根本原因分析 → Slack 通知まで一括処理するパイプラインを追加しました。あわせて ADR 18 件、ランブック 5 件、モジュール CLAUDE.md 11 個、Web ガイド 2 ページ（KO+EN）が追加され、プロジェクトドキュメントが大幅に強化されました。

主な変更点

アラートトリガー AI 診断 (ADR-009) · 4 種ウェブフック (CloudWatch/Alertmanager/Grafana/Generic) · HMAC 認証 · Slack Block Kit · ADR 18 件新規 · ランブック 5 件新規 · Web ガイド拡充

アラートトリガー AI 診断 (ADR-009)

重大度 critical のインシデント発生時に、自動的に部分 AI 診断が実行されます。

パイプラインの流れ

[CloudWatch Alarm] → SNS Topic → SQS Queue
                                    ↓
                            [EC2 Poller (15s)]
                                    ↓
[Alertmanager/Grafana/Generic] → POST /api/alert-webhook
                                    ↓
                            [alert-correlation.ts]
                                    ↓
                         [alert-diagnosis.ts (AI)]
                                    ↓
                          [Slack/SNS 送信]

サポートするソース

ソース	受信方式	正規化スキーマ
CloudWatch Alarms	SNS → SQS → EC2 ポーリング	CloudWatch イベント
Prometheus Alertmanager	直接ウェブフック（HMAC）	Alertmanager v4
Grafana Alerting	直接ウェブフック（HMAC）	Grafana unified
Generic JSON	直接ウェブフック（HMAC）	カスタムスキーマ

相関分析エンジン

src/lib/alert-correlation.ts が個別のアラートをインシデントにグループ化します:

基準	デフォルト値	説明
時間ウィンドウ	5 分	同一サービスで 5 分以内に発生したアラートをマージ
共通サービス	1 つ以上	`labels.service` または `resource` の一致
共通ネームスペース	1 つ以上	K8s アラートの `labels.namespace` の一致
重複排除	1 分	同一 `fingerprint` のアラートを 1 分以内は重複抑止
重大度エスカレーション	warning 3 件が 5 分以内	→ critical に昇格

スコープ制限付き自動診断

全体 15 セクション診断とは異なり、発火したアラートの範囲のみに制限され、1〜2 分以内に完了します:

AlertContext のビルド — 影響を受けたサービス/リソース/ネームスペース、発火時刻（since）を抽出
スコープ制限付き収集 — CloudWatch メトリクスを since 基準で ±10 分、該当リソースのみにフィルタリング
関連セクションの選択 — Compute / Network / Container など 3〜5 個のみ実行
変更検知 — Terraform state / CloudTrail の最近の変更を比較
Bedrock Sonnet 分析 — 根本原因の推定 + Next Steps の提案

// src/lib/alert-diagnosis.ts (中核インターフェース)
interface AlertContext {
  services: string[];
  resources: string[];
  namespaces: string[];
  since: Date;     // 発火時刻 − 10分
  until: Date;     // 発火時刻 + 10分
}

Slack 通知 (Block Kit)

重大度に応じたチャンネルルーティング + スレッド更新で動作します:

重大度	デフォルトチャンネル	色
`critical`	`#incidents`	🔴 赤
`warning`	`#alerts`	🟠 オレンジ
`info`	`#alerts-low`	🔵 青

最初のアラートはメインメッセージ、後続イベント（追加アラートのマージ、AI 診断結果、解決）は同一スレッドへの reply
Webhook モードと Bot Token モードの両方でスレッディングをサポート（thread_ts の再利用）
CloudWatch OK または Alertmanager resolved の受信時に ✅ 解決通知

HMAC 認証

共有シークレットは data/config.json の alertWebhookSecret に保存します:

curl -X POST https://awsops.example.com/awsops/api/alert-webhook \
  -H 'X-Alert-Source: generic' \
  -H "X-Signature-256: sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')" \
  -H 'Content-Type: application/json' \
  -d "$BODY"

アラートナレッジベース

data/alert-diagnosis/ 以下に診断記録が永続保存されます:

ファイル	内容
`incidents/<id>.json`	個別インシデント + AI 診断結果
`summary-<YYYY-MM>.json`	月間統計（top services、alert names、resolution time）

UI の Knowledge Base タブで過去の類似インシデントを検索でき、新しいインシデント発生時には類似度ベースで自動レコメンドされます。

ドキュメント大幅拡充

ADR 18 件新規 (011-028)

v1.8.0 で追加された機能の設計上の意思決定を公式化しました:

番号	テーマ
ADR-011	外部データソース統合（SSRF 防御 + allowlist）
ADR-012	SNS 通知戦略
ADR-013	自動収集調査エージェント
ADR-014	レポート生成とスケジューリング
ADR-015	AI ルーティングの優先順位
ADR-016	Bedrock モデル選択戦略
ADR-017	キャッシュウォーマーの設計
ADR-018	Cognito 認証フロー
ADR-019	SSE ストリーミング
ADR-020	HMAC ウェブフック認証
ADR-021	Admin Email 権限モデル
ADR-022	CDK スタック分離
ADR-023	マルチルート並列実行
ADR-024	i18n（ko/en）サポート
ADR-025	Code Interpreter サンドボックス
ADR-026	CloudFront + Lambda@Edge
ADR-027	OpenCost + Prometheus（EKS コスト）
ADR-028	Memory Store（会話履歴）

ランブック 5 件新規

運用の現場で実際に使えるトラブルシューティング/設定ガイド:

alert-pipeline-troubleshoot.md — ウェブフックが届かないとき、相関分析がインシデントを作れないとき、Slack に表示されないとき
cache-warmer-operations.md — キャッシュウォーマーのデバッグ、クエリの追加/削除
cognito-auth-troubleshoot.md — Lambda@Edge、HttpOnly クッキー、OAuth2 コールバックの問題
deploy-flow.md — 11 段階デプロイスクリプトの運用マニュアル
multi-account-setup.md — Aggregator 設定、クロスアカウント IAM ロール、検証手順

モジュール CLAUDE.md 11 個新規

各ソースモジュールの役割/ルール/主要ファイルを Claude コンテキストファイルとして整理:

パス	説明
`docs/CLAUDE.md`	ドキュメント構成
`runbooks/CLAUDE.md`	ランブックインデックス
`decisions/CLAUDE.md`	ADR インデックス
`agent/CLAUDE.md`	Strands Agent + 19 Lambda
`scripts/CLAUDE.md`	11 段階デプロイスクリプト
`tests/CLAUDE.md`	Vitest 構成
`infra-cdk/CLAUDE.md`	CDK スタック構成
`src/app/ai-diagnosis/CLAUDE.md`	AI 総合診断ページ
`src/app/alert-settings/CLAUDE.md`	アラート設定ページ
`src/app/k8s/CLAUDE.md`	K8s ページ
`src/lib/collectors/CLAUDE.md`	7 種 Auto-Collect エージェント

Web ガイド拡充

Docusaurus ガイドに v1.8 の機能を反映しました:

monitoring/ai-diagnosis.md — 15 セクション診断、エクスポート形式（DOCX/MD/PDF/PPTX）、スケジューリング、コスト管理のヒント
monitoring/alerts.md — アラートパイプラインの全体フロー、HMAC、相関分析、Slack スレッディング、ナレッジベース
intro.md — 40 ページ / 18 API / 11 AI ルートを反映、「AI 総合診断 & アラートパイプライン」機能ブロックを追加
faq/troubleshooting.md — Slack 通知の失敗 / AI 診断の部分失敗ケース
韓国語（docs/）+ 英語（i18n/en/docusaurus-plugin-content-docs/current/）の両方に反映

バグ修正ハイライト

項目	説明
webpack の動的 import	コレクターの動的 import に `/* webpackInclude: /\.(ts\|tsx\|js)$/ */` マジックコメントを追加 — CLAUDE.md が webpack context に含まれてビルドが失敗する問題を解決
Bedrock モデル ID	アラート診断に `global.anthropic.claude-sonnet-4-6` を使用
Slack スレッドの再利用	Webhook モードでも `thread_ts` を保存して後続イベントに reply
レポートダウンロード	S3 presigned URL の代わりにプロキシ URL を使用 — STS セッション期限切れ時の 404 を解決
SNS メール	マークダウンをプレーンテキストに変換してから送信
キャッシュウォーマー	Monitoring クエリを除外（CloudWatch FDW 呼び出しが pg Pool を枯渇させるため）
Silent なクッキー削除	HttpOnly クッキーは `POST /api/auth` によるサーバーサイド削除

主なファイル変更

ファイル	変更内容
`src/app/api/alert-webhook/route.ts`	4 種ソースのウェブフック受信 + HMAC 検証 + 相関分析トリガー + アクティブインシデント GET
`src/app/api/notification/route.ts`	Slack Block Kit / SNS 送信（重大度チャンネルルーティング、マークダウン→プレーンテキスト）
`src/lib/alert-types.ts`	ソース別の正規化関数（CloudWatch/Alertmanager/Grafana/Generic）
`src/lib/alert-correlation.ts`	相関分析エンジン（30 秒バッファ、時間/サービス/リソースのマッチング）
`src/lib/alert-diagnosis.ts`	診断オーケストレーター（戦略選択、並列コレクター、AlertContext スコープ）
`src/lib/alert-knowledge.ts`	ナレッジベース（JSONL 保存、月間サマリー、類似度検索）
`src/lib/slack-notification.ts`	Slack クライアント（Bot Token/Webhook、スレッド更新）
`src/lib/alert-sqs-poller.ts`	SQS バックグラウンドポーラー（SNS→SQS→EC2、DLQ、Rate Limit）
`src/app/alert-settings/page.tsx`	アラート設定管理ページ（Admin 専用）
`docs/decisions/ADR-011~028.md`	18 個の ADR を新規追加
`docs/runbooks/*.md`	5 個のランブックを新規追加
`web/docs/monitoring/ai-diagnosis.md`	AI 総合診断ガイド
`web/docs/monitoring/alerts.md`	アラートパイプラインガイド

バージョン比較

項目	v1.8.0	v1.8.1	変更
アラートパイプライン	—	ウェブフック + 相関分析 + AI 診断	新規
サポートするアラートソース	—	4 種 (CloudWatch/Alertmanager/Grafana/Generic)	新規
Slack 通知	—	Block Kit + スレッド更新	新規
ADR	10 個 (001-010)	28 個 (001-028)	+18
ランブック	—	5 個	新規
モジュール CLAUDE.md	7 個	18 個	+11
Web ガイドページ	39	41	+2 (ai-diagnosis, alerts)

参考

ADR-009: アラートトリガー AI 診断
ADR-012: SNS 通知戦略
ADR-013: 自動収集調査エージェント
ADR-020: HMAC ウェブフック認証

アラートトリガー AI 診断 (ADR-009)​

パイプラインの流れ​

サポートするソース​

相関分析エンジン​

スコープ制限付き自動診断​

Slack 通知 (Block Kit)​

HMAC 認証​

アラートナレッジベース​

ドキュメント大幅拡充​

ADR 18 件新規 (011-028)​

ランブック 5 件新規​

モジュール CLAUDE.md 11 個新規​

Web ガイド拡充​

バグ修正ハイライト​

主なファイル変更​

バージョン比較​

参考​