エラーの根本原因の分析を LLM を利用して支援するサンプル実装です。
本サンプルで試せることは以下の通りです。
障害分析支援
あらかじめ定義されたログの保管先から、ユーザが指定した時間範囲でログを取得し、そのログを LLM で情報抽出や要約を行い、障害分析を助ける情報を Slack に返します。 機能の動作イメージは、障害分析支援 を参照ください。
メトリクス分析支援
ユーザから与えられた質問に対し、生成 AI が必要なメトリクスを選定、そのメトリクスのデータを元に質問に回答する機能を追加しました。 詳しくは、メトリクス分析支援を参照ください。
Findings レポート
Security Hub と GuardDuty の Findings を生成 AI が解説するレポートを作成する機能を追加しました。 詳しくは、Findings レポートを参照ください。
main- 本ブランチです。Slack App を利用したバージョンです。chatbot-customaction- Slack App の代わりに、Amazon Q Developer in chat applications の Custom Action という機能を利用して、入力フォームを実装したバージョンです。Slack App が利用できない環境や、Slack App を管理したくない場合は、こちらをご利用ください。(こちらはまだAgent対応できておりません)
既存ワークロードの範囲は、既に実装されているという前提です。 本サンプルは、CloudWatch Logs にログが出力されていれば、お試しいただけます。
- 対象システムで、メトリクスなどに設定したアラームが発火し、Amazon SNS と Amazon Q Developer in chat applications を通じ Slack に通知が届きます
- FA2 が通知をトリガーに入力フォームを表示します
- 表示されたフォームに
ログの取得時間範囲とアラームからわかるイベント情報を入力し、障害分析をリクエストします - FA2 は Lambda 上で実行され、ReACT（Reasoning + Acting）アルゴリズムを使用したエージェントが障害分析を行います：
- 思考ステップ（Thinking）: エージェントは状況を分析し、次に実行すべきアクションを決定します
- 行動ステップ（Acting）: 決定されたツールを実行します（例：CloudWatch Logsからのログ取得、メトリクスの分析など）
- 観察ステップ（Observing）: ツールの実行結果を観察し、新たな情報を収集します
- サイクル繰り返し: 十分な情報が集まるまで、思考→行動→観察のサイクルを繰り返します
- 結果生成フェーズ: 収集した情報に基づいて最終的な障害分析レポートを生成します
- エージェントは以下のツールを使って情報を収集・分析します：
- metrics_tool: CloudWatchメトリクスを取得・分析
- logs_tool: CloudWatch Logsからログを取得・分析
- athena_log_tool: Athenaから監査ログやALBのアクセスログを取得・分析
- xray_tool: X-Rayからトレース情報を取得・分析
- kb_tool: Knowledge Baseからドキュメントを検索
- 分析が完了すると、エージェントは以下の情報を含む詳細な障害分析レポートを生成します：
- 障害概要
- 根本原因（重要度と確信度を含む）
- 参照したログ/メトリクス
- 時系列分析
- 推奨される対応策
- 再発防止策
- 生成されたレポートはSlackに送信され、ユーザーに提供されます
FA2のコアとなるReACTエージェントは、以下のような詳細なプロセスで動作します：
-
セッション管理：
- 各分析リクエストに対して一意のセッションIDが生成されます
- セッション状態はDynamoDBに保存され、Lambda関数の実行間で維持されます
- セッション情報には思考履歴、実行したツール、収集したデータなどが含まれます
-
思考プロセス：
- 初回の思考では、エラー内容と利用可能なツールの情報を基に分析戦略を立てます
- 2回目以降は、これまでに収集した情報を考慮して次のアクションを決定します
- 思考の結果は構造化された形式で出力され、次のアクションが決定されます
-
ツール実行：
- 選択されたツールは適切なパラメータで実行されます
- 実行結果はセッション状態に記録され、データ収集状況が更新されます
- 各ツールの実行結果は、次の思考サイクルの入力として使用されます
-
サイクル制御：
maxAgentCyclesパラメータで最大サイクル数を制御できます（デフォルト: 5）- 十分な情報が集まった場合や最大サイクル数に達した場合、最終回答生成フェーズに移行します
- Bedrockのレート制限に達した場合は、適切なエラーハンドリングが行われます
-
最終回答生成：
- 収集したすべての情報を統合し、構造化された障害分析レポートを生成します
- レポートはMarkdown形式でSlackに送信され、ファイルとして共有されます
- AWS Cloud Development Kit (CDK) が利用できること
- 本サンプルは CDK で実装されています
- 分析したいログが含まれている、CloudWatch Logs のロググループがあること
- 加えて、AWS CloudTrail、Application Load Balancer (ALB) のアクセスログを利用する場合、Amazon Athena のデータベースが作成されていること
- AWS X-Ray のトレース情報も利用する場合、該当システムの AWS X-Ray トレースが取得できていること
- Amazon Bedrock で必要なモデルへのモデルアクセスのアクセス許可をしていること
- 既存ワークロードで設定した Amazon Q Developer in chat applications から Slack にアラームの通知が来ることを確認していること
- FA2 のテスト利用のための既存ワークロードがない、もしくは利用できない場合、FA２のお試し環境の作り方を参考に、環境を作ることもできます
- 利用したい Slack ワークスペースに Slack App を登録できる権限を持っていること
- Amazon API Gateway のコンソールで、CloudWatch ログ記録を有効にしていること
- 未設定の場合は、こちらの記事の[解決策]にある、[CloudWatch へのログ記録用の IAM ロールを作成する]と[API ゲートウェイコンソールに IAM ロールを追加する]を実施してください
- Slack apiを開き、[create New App]をクリックします
- [From scratch]を選び、App Name の入力と開発するときに使うワークスペースを選択し、[Create App]をクリックします
- Slack apiに自分が作成したアプリが表示されるので、それを選択します
- 左メニューの[Basic Information]をクリックし、[Signing Secret]を確認し、次のコマンドを実行し、Secrets Manager に登録します
$ aws secretsmanager create-secret --name SlackSigningSecret --secret-string XXXXXXXXXXXXXXXXXXXXXXXX --profile {your_profile}
- 左メニューの[OAuth & Permissions]をクリックし、[Scopes]で、
channels:read,chat:write,files:writeを追加します - ページ上部の、[OAuth Tokens for Your Workspace]の[Install to Workspace]をクリックし、Slack Appをワークスペースにインストールします
- リダイレクトされて戻ってきたページに[Bot User OAuth Token]が表示されるので、次のコマンドを実行し、Secrets Manager に登録します
$ aws secretsmanager create-secret --name SlackAppToken --secret-string xxxx-1111111111111-1111111111111-XXXXXXXXXXXXXXXXXXXXXXXX --profile {your_profile}
次の記載を参考に、parameter_template.tsをコピーし、parameter.ts を作成した上で、それぞれの値を変更してください。
// 例: Slack App 版で、Claude 3.7 Sonnet を利用し、CloudWatch Logsを検索対象とした場合の設定
export const devParameter: AppParameter = {
env: {
account: "123456789012",
region: "us-west-2",
},
language: "ja",
envName: "Development",
modelId: "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
slackAppTokenKey: "SlackAppToken",
slackSigningSecretKey: "SlackSigningSecret",
architectureDescription: `
あなたが担当するワークロードは、ALB, EC2, Aurora で構成されています。また、EC2 上に Spring アプリケーションがデプロイされています。`,
cwLogsLogGroups: [
"/ec2/demoapp",
"/ec2/messages",
"/aws/application-signals/data",
],
cwLogsInsightQuery: "fields @message | limit 100",
xrayTrace: false,
slashCommands: {
insight: true,
findingsReport: true
},
knowledgeBase: true,
embeddingModelId: "amazon.titan-embed-text-v2:0",
maxAgentCycles: 5 // ReACTエージェントが実行する最大サイクル数
};
| パラメータ | 値の例 | 概要 |
|---|---|---|
env.account |
"1234566789012" |
デプロイ先 AWS アカウントのアカウント ID |
env.region |
"us-west-2" |
デプロイ先リージョン |
language |
"ja" |
プロンプトや UI の言語設定。en または ja のどちらかを指定します |
envName |
"Development" |
環境名。Development や Staging など |
modelId |
"us.anthropic.claude-3-7-sonnet-20250219-v1:0" |
推論品質が高いモデルを指定します。Amazon Bedrock で定義されたモデル ID を指定します。モデルアクセスで許可しているものを指定してください |
slackAppTokenKey |
"SlackAppToken" |
AWS Secrets Manager から SlackAppToken を取得するためのキー名。Slack App の登録で利用したキー名を指定してください |
slackSingingSecretKey |
"SlackSigningSecret" |
AWS Secrets Manager から SlackSigningSecret を取得するためのキー名。Slack App の登録で利用したキー名を指定してください |
architectureDescription |
"あなたが担当するワークロードは、ALB, EC2, Aurora で構成されています。また、EC2 上に Spring アプリケーションがデプロイされています。" |
障害分析の対象となるシステムを説明する文章です。プロンプトに組み込まれますので、AWSのサービス名や要素技術を含める、簡潔にする、などを心がけてください。 |
cwLogsLogGroups |
["/ec2/demoapp", "/ec2/messages", "/aws/application-signals/data"] |
ログを取得したい Amazon CloudWatch Logs のロググループを指定します。最大 50 個まで指定可能です |
cwLogsInsightQuery |
"fields @message | limit 100" |
CloudWatch Logs Insight で利用したいクエリを指定します。コンテキストウィンドウとの兼ね合いから、デフォルトでは、100 件に制限しています（実際のプロンプトに応じて、調整ください） |
databaseName |
"athenadatacatalog" |
Amazon Athena のデータベース名。Athena を使ってログ検索を行いたい場合は必須です |
albAccessLogTableName |
"alb_access_logs" |
ALB のアクセスログのテーブル名。今回のサンプルでは、Athena で ALB のアクセスログのログ検索を実装したため、利用する場合 ALB のアクセスログテーブル名を指定します |
cloudTrailLogTableName |
"cloud_trail_logs" |
AWS CloudTrail のログのテーブル名。今回のサンプルでは、Athena で CloudTrail の監査ログのログ検索を実装したため、利用する場合 CloudTrail のログテーブル名を指定します |
xrayTrace |
true |
分析対象に AWS X-Ray のトレース情報を含めるかどうか決めるためのパラメータ |
slashCommands |
{"insight": true, "findingsReport": true} |
insight や findings-report コマンドに関連するリソースのデプロイを有効にします |
detectorId |
"xxxxxxxxxxx" |
findings-report を利用する場合には必須です。アカウントで定義されている detectorId を設定してください |
knowledgeBase |
true |
ナレッジベースを利用する場合は true を設定ください。利用しない場合は、false です。 |
embeddingModelId |
"amazon.titan-embed-text-v2:0" |
ナレッジベースを利用する場合に任意で埋め込みモデルが設定できます。何も設定しない場合は、 amazon.titan-embed-text-v2:0 が設定されます。変更する場合は、lib/constructs/aurora-serverless.ts の 120 行目の VectorDimensions も併せて変更してください |
maxAgentCycles |
5 |
ReACTエージェントが実行する最大サイクル数を指定します。デフォルトは5です。 |
lambda/lib/prompts.ts にそれぞれの推論で利用するプロンプトが記載されています。
それぞれのプロンプトでは、parameter.ts にある、architectureDescription を使って、対象となるワークロードのアーキテクチャの説明文を取得しています。
ご自身が FA2 をデプロイする環境に合わせ、このアーキテクチャの説明文を変更してください。
また、デプロイ後のテストで、期待した結果が得られない場合は、createFailureAnalysisPrompt 関数に記載されているプロンプトをチューニングしてください。
まず、障害原因の仮説を図示する機能でLambda関数のLayerが必要となります。 そこで、最初にLayerに必要なモジュールをインストールするコマンドを実行してください。 続いて、通常のCDKのデプロイのコマンドを実施します。
$ npm run build:layer // 障害原因の仮説を図示する機能を利用するために実施します
$ npm install
$ npx cdk bootstrap --profile {your_profile}
$ npx cdk deploy --all --profile {your_profile} --require-approval never
Note
failure-analysis-assistant/lambda/functions/fa2-lambda/main.mts の、// Additional process.の記載から始まる箇所が、障害原因の仮説の図を生成する処理になります。
図の生成が不要の場合、この部分はコメントアウトまたは削除してください。
Amazon Bedrock knowledge Base を有効にした場合、デプロイが終わると、ナレッジベースやデータソースがプロビジョニングされています。 必要なドキュメント（AWSの公式ドキュメントのPDFやワークロードに関するドキュメント）をデータソースである S3 にアップロードし、データソースの同期を行なってください。 デフォルトでは、データは何も登録されていません。
- CDK デプロイ後に、Amazon API Gateway のエンドポイント URL を確認します
- Slack apiを開き、表示された画面の左メニューにある、[Interactivity & Shortcuts]を選択し、[Interactivity]を ON にしたあと、[Request URL]に 1 で確認した Amazon API Gateway のエンドポイントを入力し（例: https://{API Gateway のエンドポイント}/v1/slack/events）、[Save Changes]をクリックします
- API のリソース名は変更していなければ、例の通り、/slack/events となります
- 次に、左メニューの[Event Subscriptions]をクリックし、[Enable Events]を ON にしたあと、[Interactivity]と同様に、[Reqeust URL]を設定します
- 同じ画面の[Subscribe to bot events]を開き、[Add Bot User Event]をクリックし、
message.channelsを追加し、[Save Changes]をクリックします - 手順4で行ったトークンのスコープ変更に伴い、Slack App の再インストールが必要になります。画面の上の方に再インストールを促すポップアップが出るので、それをクリックして、対象のチャンネルへ Slack App を再インストールします
- または、[OAuth & Permissions]を開き、[Reinstall to {あなたのワークスペース名}]をクリックし、再インストールします
- 対象のチャンネルへ Slack App を参加させます。追加するには、対象のチャンネルを開き、チャンネル名をクリックします。[インテグレーション]を選択し、[アプリを追加する]をクリックします。FA2（またはご自身が登録したアプリ名）を探し、[追加]ボタンをクリックします。表示される指示に従ってアプリをインストールします
障害分析支援機能は、デフォルトでは、アラームが発生したタイミングでフォームが表示されます。 ただ、好きなタイミングで実行したい場合もあるかと思います。 以下の設定を入れることで、お好きなタイミングで障害分析支援機能を実行するためのフォームを表示することができます。
-
左メニューの[Slash Commands]をクリックし、[Create New Command]をクリックします
-
以下の表のように値を入力し、すべて入力したら、[Save]をクリックします
項目名 値 Command /fa2 Request URL Request URL と同じ URL Short Description Invoke FA2 interactively
-
-
左メニューの [App Home] をクリックし、[Message Tab] にある [Allow users to send Slash commands and messages from the messages tab] にチェックを入れます
- これで、Slack App の DM 欄でメトリクス分析支援の実行・結果受領がしやすくなります
-
左メニューの [OAuth & Permissions] をクリックし、[Scopes]で、
commandsを追加します
ログ出力元の対象システムでなんらかエラーを起こしてください。すると、Slack チャンネルに以下のようなアラームが表示されます。
アラームが表示されると、FA2 が反応し、以下のようなフォームが表示されます。
先程表示されたアラームを確認し、アラームの内容と、ログを取得したい時間範囲を表示されたフォームへ入力します。
※Amazon Q Developer in chat applications の示す datapoints は GMT で表記されているため、フォームには JST に変換した上で入力してください。
ボタンをクリックするとリクエストが受け付けられます。
少し待つと、回答が Slack に表示されます。
以下のコマンドを実行し、デプロイしたリソースを削除してください。
$ npx cdk destroy --profile {your_profile}
本ソースコードはサンプルのため、Amazon API Gateway に対し、AWS WAF をアタッチしていません。 Slack のエンドポイントはパブリックに公開されているため、攻撃対象となる可能性があります。 本番利用される際は、セキュリティリスク軽減のため、AWS WAF のご利用を検討してください。
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.