DevOps Agentの調査結果を、Amazon Qでアラーム通知のスレッドに返してみた

import * as cdk from "aws-cdk-lib";
import * as chatbot from "aws-cdk-lib/aws-chatbot";
import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
import * as actions from "aws-cdk-lib/aws-cloudwatch-actions";
import * as events from "aws-cdk-lib/aws-events";
import * as targets from "aws-cdk-lib/aws-events-targets";
import * as iam from "aws-cdk-lib/aws-iam";
import * as lambda from "aws-cdk-lib/aws-lambda";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import * as sns from "aws-cdk-lib/aws-sns";
import { Construct } from "constructs";

export class AlarmThreadStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const slackWorkspaceId = this.node.getContext("slackWorkspaceId");
    const slackChannelId = this.node.getContext("slackChannelId");
    const agentSpaceId = this.node.getContext("agentSpaceId");
    const agentSpaceArn = `arn:aws:aidevops:${this.region}:${this.account}:agentspace/${agentSpaceId}`;

    // アラーム通知とカスタム通知の両方を、このトピックに送る
    const topic = new sns.Topic(this, "Topic", {
      topicName: "alarm-notification-topic",
    });

    // 手で ALARM にする用のアラーム。データが無いと OK に戻る
    const alarm = new cloudwatch.Alarm(this, "Alarm", {
      alarmName: "sample-alarm",
      metric: new cloudwatch.Metric({
        namespace: "Sample/App",
        metricName: "Errors",
        period: cdk.Duration.minutes(1),
        statistic: "Sum",
      }),
      threshold: 1,
      evaluationPeriods: 1,
      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
    });
    alarm.addAlarmAction(new actions.SnsAction(topic));
    alarm.addOkAction(new actions.SnsAction(topic));

    // ボタンから呼ばれ、DevOps Agent の調査を作る
    const investigateFn = new NodejsFunction(this, "InvestigateFunction", {
      entry: "lambda/investigate/index.mjs",
      runtime: lambda.Runtime.NODEJS_24_X,
      timeout: cdk.Duration.seconds(10),
      environment: { AGENT_SPACE_ID: agentSpaceId },
      // DevOps Agent のクライアントは新しいため、実行環境の SDK に頼らずまとめて入れる
      bundling: { externalModules: [] },
    });
    investigateFn.addToRolePolicy(
      new iam.PolicyStatement({ actions: ["aidevops:CreateBacklogTask"], resources: [agentSpaceArn] }),
    );
    investigateFn.addToRolePolicy(new iam.PolicyStatement({ actions: ["cloudwatch:DescribeAlarms"], resources: ["*"] }));

    // 調査が終わったら、要約をアラーム通知と同じトピックに送る
    const summaryFn = new NodejsFunction(this, "SummaryFunction", {
      entry: "lambda/summary/index.mjs",
      runtime: lambda.Runtime.NODEJS_24_X,
      timeout: cdk.Duration.seconds(30),
      environment: { TOPIC_ARN: topic.topicArn },
      bundling: { externalModules: [] },
    });
    summaryFn.addToRolePolicy(
      new iam.PolicyStatement({
        actions: ["aidevops:GetBacklogTask", "aidevops:ListJournalRecords"],
        resources: [agentSpaceArn],
      }),
    );
    topic.grantPublish(summaryFn);

    // 同じ source で対処（Mitigation）のイベントも届くため、調査の終わりの 3 つに絞る
    new events.Rule(this, "InvestigationEndRule", {
      eventPattern: {
        source: ["aws.aidevops"],
        detailType: ["Investigation Completed", "Investigation Failed", "Investigation Timed Out"],
      },
      targets: [new targets.LambdaFunction(summaryFn)],
    });

    // チャンネルロール: 通知の表示に使う読み取りと、ボタンの Lambda の呼び出しだけ
    const channelPermissions = [
      new iam.PolicyStatement({ actions: ["lambda:InvokeFunction"], resources: [investigateFn.functionArn] }),
      new iam.PolicyStatement({
        actions: ["cloudwatch:Describe*", "cloudwatch:Get*", "cloudwatch:List*"],
        resources: ["*"],
      }),
    ];
    const chatbotRole = new iam.Role(this, "ChatbotRole", {
      assumedBy: new iam.ServicePrincipal("chatbot.amazonaws.com"),
      inlinePolicies: { ButtonOnly: new iam.PolicyDocument({ statements: channelPermissions }) },
    });
    const guardrail = new iam.ManagedPolicy(this, "ChatbotGuardrail", { statements: channelPermissions });

    // ALARM の通知に「調査を依頼」のボタンを出す
    const investigateAction = new chatbot.CfnCustomAction(this, "InvestigateAction", {
      actionName: "alarm-thread-request-investigation",
      definition: {
        commandText: `lambda invoke --function-name ${investigateFn.functionName} --payload '{"alarmName":"$AlarmName"}' --region ${this.region}`,
      },
      attachments: [
        {
          notificationType: "CloudWatch",
          buttonText: "DevOps Agent に調査を依頼",
          variables: { AlarmName: "event.AlarmName", State: "event.NewStateValue" },
          criteria: [
            { variableName: "AlarmName", operator: "HAS_VALUE" },
            { variableName: "State", operator: "EQUALS", value: "ALARM" },
          ],
        },
      ],
    });

    new chatbot.CfnSlackChannelConfiguration(this, "SlackChannel", {
      configurationName: "alarm-channel",
      iamRoleArn: chatbotRole.roleArn,
      slackWorkspaceId,
      slackChannelId,
      snsTopicArns: [topic.topicArn],
      guardrailPolicies: [guardrail.managedPolicyArn],
      customizationResourceArns: [investigateAction.attrCustomActionArn],
      loggingLevel: "INFO",
    });

    new cdk.CfnOutput(this, "TopicArn", { value: topic.topicArn });
    new cdk.CfnOutput(this, "AlarmArn", { value: alarm.alarmArn });
  }
}

import * as cdk from "aws-cdk-lib";
import { AlarmThreadStack } from "../lib/alarm-thread-stack";

const app = new cdk.App();

new AlarmThreadStack(app, "AlarmThreadStack", {
  env: { region: "ap-northeast-1" },
});

{
  "app": "pnpm exec ts-node --prefer-ts-exts bin/app.ts",
  "context": {
    "slackWorkspaceId": "<ワークスペース ID>",
    "slackChannelId": "<チャンネル ID>",
    "agentSpaceId": "<Agent Space ID>"
  }
}

pnpm exec cdk deploy

Outputs:
AlarmThreadStack.AlarmArn = arn:aws:cloudwatch:ap-northeast-1:123456789012:alarm:sample-alarm
AlarmThreadStack.TopicArn = arn:aws:sns:ap-northeast-1:123456789012:alarm-notification-topic

import { CloudWatchClient, DescribeAlarmsCommand } from "@aws-sdk/client-cloudwatch";
import { CreateBacklogTaskCommand, DevOpsAgentClient } from "@aws-sdk/client-devops-agent";

const cloudwatch = new CloudWatchClient({});
const devopsAgent = new DevOpsAgentClient({});
const agentSpaceId = process.env.AGENT_SPACE_ID;

// 要約の Lambda は、題名からこの文字列を外してアラーム名にする
const TITLE_PREFIX = "Slack から調査依頼: ";

// ボタンから呼ばれる。戻り値の文字列は、Amazon Q がボタンへの返事としてスレッドに投稿する
export const handler = async (event) => {
  const alarmName = event?.alarmName;
  // 今 ALARM のものだけ調査する
  const { MetricAlarms = [] } = await cloudwatch.send(new DescribeAlarmsCommand({ AlarmNames: [alarmName] }));
  const alarm = MetricAlarms[0];
  if (alarm?.StateValue !== "ALARM") {
    return `${alarmName} は今 ALARM ではないため、調査を始めません。`;
  }

  await devopsAgent.send(
    new CreateBacklogTaskCommand({
      agentSpaceId,
      taskType: "INVESTIGATION",
      priority: "MEDIUM",
      title: `${TITLE_PREFIX}${alarmName}`,
      description: `Slack のアラーム通知のボタンから調査の依頼がありました。対象は CloudWatch アラーム ${alarmName} です。アラームの理由: ${alarm.StateReason}`,
    }),
  );
  return `調査を依頼しました（アラーム: ${alarmName}）。結果はこのスレッドに投稿されます。`;
};

import { DevOpsAgentClient, GetBacklogTaskCommand, ListJournalRecordsCommand } from "@aws-sdk/client-devops-agent";
import { PublishCommand, SNSClient } from "@aws-sdk/client-sns";

const devopsAgent = new DevOpsAgentClient({});
const sns = new SNSClient({});
const topicArn = process.env.TOPIC_ARN;

const TITLE_PREFIX = "Slack から調査依頼: ";

// DevOps Agent の調査が終わったときのイベント（EventBridge）で呼ばれる
export const handler = async (event) => {
  const { agent_space_id: agentSpaceId, task_id: taskId } = event.detail.metadata;

  // ボタンから起動した調査だけを扱う。題名の末尾がアラーム名
  const { task } = await devopsAgent.send(new GetBacklogTaskCommand({ agentSpaceId, taskId }));
  if (!task.title.startsWith(TITLE_PREFIX)) {
    return;
  }
  const alarmName = task.title.slice(TITLE_PREFIX.length);

  const link = `<https://${agentSpaceId}.aidevops.global.app.aws/investigation/${taskId}|調査の詳細を見る>`;
  let description = `${link}\n\n${event["detail-type"]}`;
  if (event["detail-type"] === "Investigation Completed") {
    const summary = await readSummary(agentSpaceId, task.executionId);
    description = [
      link,
      `*インシデント*\n${summary.incident ?? "（未記載）"}`,
      `*原因*\n${summary.cause ?? "（未記載）"}`,
      `*対応*\n${summary.mitigation ?? "（未記載）"}`,
    ].join("\n\n");
  }

  const message = {
    version: "1.0",
    source: "custom",
    content: {
      textType: "client-markdown",
      title: "DevOps Agent の調査結果",
      description: description.slice(0, 8000), // description の上限
    },
    metadata: {
      // アラーム通知のスレッドに入れる
      threadId: `arn:aws:cloudwatch:${event.region}:${event.account}:alarm:${alarmName}`,
      enableCustomActions: false,
    },
  };
  await sns.send(new PublishCommand({ TopicArn: topicArn, Message: JSON.stringify(message) }));
};

// Web App の「概要」タブの中身（調査中に何度も書き直される）の、最後の 1 件から 3 項目を取り出す
async function readSummary(agentSpaceId, executionId) {
  const { records } = await devopsAgent.send(
    new ListJournalRecordsCommand({
      agentSpaceId,
      executionId,
      recordType: "ui_investigation_summary",
      order: "DESC",
      limit: 1,
    }),
  );
  const texts = new Map();
  const walk = (node) => {
    if (typeof node?.id === "string" && typeof node.text === "string") {
      texts.set(node.id, node.text);
    }
    node?.children?.forEach(walk);
  };
  walk(JSON.parse(records[0].content).content);
  return {
    incident: texts.get("summary__incident"),
    cause: texts.get("summary__cause"),
    mitigation: texts.get("summary__mitigation"),
  };
}

#!/usr/bin/env bash
# threadId を付けたカスタム通知を、アラーム通知と同じトピックに送る
# 使い方: scripts/publish.sh <threadId> <タイトル>
set -euo pipefail

THREAD_ID="$1"
TITLE="$2"
TOPIC_ARN=$(aws sns list-topics --query "Topics[?ends_with(TopicArn, ':alarm-notification-topic')].TopicArn" --output text)

MESSAGE=$(cat <<EOF
{
  "version": "1.0",
  "source": "custom",
  "content": {
    "textType": "client-markdown",
    "title": "${TITLE}",
    "description": "threadId: ${THREAD_ID}"
  },
  "metadata": {
    "threadId": "${THREAD_ID}",
    "enableCustomActions": false
  }
}
EOF
)

aws sns publish --topic-arn "$TOPIC_ARN" --message "$MESSAGE"

aws cloudwatch set-alarm-state --region ap-northeast-1 --alarm-name sample-alarm --state-value ALARM --state-reason "検証のため手で ALARM にする"

scripts/publish.sh arn:aws:cloudwatch:ap-northeast-1:123456789012:alarm:sample-alarm "1/2 threadId=アラームの ARN"

scripts/publish.sh sample-alarm "2/2 threadId=アラーム名"

scripts/publish.sh arn:aws:cloudwatch:ap-northeast-1:123456789012:alarm:sample-alarm "4 threadId=アラームの ARN（ALARM の直後）"

scripts/publish.sh arn:aws:cloudwatch:ap-northeast-1:123456789012:alarm:sample-alarm "5 threadId=アラームの ARN（2 時間後の 1 件目）"

scripts/publish.sh arn:aws:cloudwatch:ap-northeast-1:123456789012:alarm:sample-alarm "6 threadId=アラームの ARN（2 時間後の 2 件目）"

aws logs tail /aws/chatbot/alarm-channel --region us-east-1 --since 1h --format short | grep "Sending message"

2026-10-28T02:11:25 Sending message to existing Slack thread started at approx 2026-10-27T13:20:24.993Z (Workspace: <ワークスペース ID>, Channel: alarm-notify) with title: 🚨 CloudWatch Alarm | sample-alarm | ap-northeast-1 | Account: 123456789012
2026-10-28T02:19:24 Sending message to Slack (Workspace: <ワークスペース ID>, Channel: alarm-notify) with title: ✅ CloudWatch Alarm | sample-alarm | ap-northeast-1 | Account: 123456789012

for i in $(seq 1 20); do
  aws cloudwatch put-metric-data --region ap-northeast-1 --namespace Sample/App --metric-name Errors --value 5
  sleep 30
done