Amazon Q Developer で SNS のアラートを Slack に届ける — 1 通の SNS メッセージで、サブスクリプションのプロトコルごとに本文を分ける

Amazon Q Developer はプレーンテキストの SNS メッセージを捨てます。MessageStructure=json で publish すると、1 回の呼び出しでメールにはプレーンテキスト、Slack にはカスタム通知を送れます。

白いカードの中央に、青・緑・赤・黄の丸いバーを組んだハッシュ形のマークと、黒い slack の文字。その下に小さな青い雲と from Salesforce の文字がある Slack のロゴ
目次

はじめに

AWS で運用しているドキュメント翻訳パイプラインのアラートは、今はすべて SNS のメールで届きます。このうちエラーアラートを、チームの Slack チャンネルにも流したいと考えました。 Amazon Q Developer in chat applications(旧 AWS Chatbot)を使うと、コードを書かずに SNS トピックを Slack につなげられます。そこで本番に導入する前に、自分のワークスペースで試してみました。

CloudWatch アラームは Slack に届きましたが、自分のコードが publish したメッセージはすべて黙って捨てられていました。Amazon Q Developer が受け付けるのは、独自のカスタム通知の JSON だけだからです。

解決策は、MessageStructure=json を付けて SNS メッセージを 1 通だけ publish することです。メールにはプレーンテキストの本文を、Slack にはカスタム通知の JSON を届けられます。 どのアラートの送信元も Publish の呼び出しは 1 回のままで、CloudWatch アラームもこれまでどおり Slack に届きます。

アラートが Slack に届くまで

Amazon Q Developer in chat applications は、チャンネル設定(channel configuration)の単位で設定します。チャンネル設定には、次の 3 つを指定します。

  1. Slack チャンネル:アラートを受け取るチャンネル。1 つのチャンネル設定に 1 つだけ指定します。
  2. SNS トピック:このチャンネルに通知を流すトピック。複数指定できます。
  3. IAM ロール:チャンネルで入力されたコマンドを実行するときのロール。

チャンネル設定を作ると、Amazon Q Developer が各トピックに HTTPS でサブスクライブします。トピックにもともとあったメールのサブスクリプションはそのまま残ります。

手作業が残る手順は 2 つあります。

  1. AWS のアプリを承認する:Slack ワークスペースにアクセスできる人が OAuth 画面で承認します。この画面は Amazon Q Developer のコンソールから開きますが、そのコンソールは米国東部(オハイオ)でしか動きません。
  2. プライベートチャンネルに招待する:プライベートチャンネルでは /invite @Amazon Q と入力します。これをしないと、そのチャンネルには何も届きません。

それ以外はすべて CDK で書けます。 aws-cdk-lib/aws-chatbot の SlackChannelConfiguration には、省略できる role プロパティがあります。下のコードは role を指定していないので、CDK が信頼ポリシーだけを持ち権限の無いロールを自動で作ります。私はその上に ReadOnlyAccess をガードレールとして付けました。ガードレールは、ロールの権限にかかわらず、チャンネルで実行するコマンドができることの上限を決める IAM ポリシーです。

このチャンネルはアラートを受け取るだけです。チャンネルで @Amazon Q にコマンドを入力しても、アカウントの中は何も変更できません。

core-stack.ts
new chatbot.SlackChannelConfiguration(this, 'SlackAlerts', {
slackChannelConfigurationName: 'dev-alerts',
slackWorkspaceId: 'T0123456789',
slackChannelId: 'C0123456789',
notificationTopics: [notificationTopic, opsAlertTopic],
guardrailPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName('ReadOnlyAccess')],
loggingLevel: chatbot.LoggingLevel.ERROR,
});

スタックは東京リージョンにあります。Amazon Q Developer のコンソールはオハイオでしか動きませんが、チャンネル設定は米国用のスタックを別に作らなくても東京のスタックからデプロイできました。

プレーンテキストの SNS メッセージが Slack に届かなかった理由

Amazon Q Developer はプレーンテキストの SNS メッセージを捨て、ログを 1 行残すだけです。

/aws/chatbot/<configuration name> (us-east-1)
Event received is not supported (see https://docs.aws.amazon.com/chatbot/latest/adminguide/related-services.html ): {"type":"Notification", … "message":"TEST1b: …", …}

Amazon Q Developer は、CloudWatch アラームのように対応している AWS サービスの通知なら自分で整形します。それ以外のメッセージには、カスタム通知の形式を求めます。 カスタム通知は JSON オブジェクトで、version に "1.0"、source に "custom" を指定し、content.description を持たせます。

{
"version": "1.0",
"source": "custom",
"content": {
"textType": "client-markdown",
"title": ":x: [prod] Translation failed",
"description": "*File ID*: `123456`"
}
}

カスタム通知には必ず「Custom notification delivered by Amazon Q Developer」という固定のフッターが付きます。この形式には、フッターを消すフィールドがありません。

1 通のメッセージで、サブスクリプションのプロトコルごとに本文を分ける

MessageStructure=json を使うと、1 回の Publish 呼び出しでサブスクリプションのプロトコルごとに別の本文を送れます。 このとき Message は JSON オブジェクトになり、キーがプロトコル名、値が文字列です。 default は必須で、専用のキーが無いプロトコルすべてに使われます。https は HTTPS のサブスクライバーに使われます。Amazon Q Developer は HTTPS でサブスクライブしているので、こちらの本文を受け取ります。

notifier.py
def publish_notice(client, *, topic_arn: str, notice: Notice) -> None:
message = {
"default": email_text(notice),
"https": json.dumps(slack_notice(notice), ensure_ascii=False),
}
client.publish(
TopicArn=topic_arn,
Subject=subject_safe(notice.subject)[:99],
Message=json.dumps(message, ensure_ascii=False),
MessageStructure="json",
)

https の値は JSON 文字列の中に入った JSON なので、2 回エンコードされます。 メールにはこれまでどおり default の本文と Subject が届きます。

1 通のメッセージで、サブスクリプションのプロトコルごとに本文を分けるアプリのコードが MessageStructure=json で Publish を 1 回呼び、CloudWatch アラームも同じ SNS トピックに通知する。トピックは default の本文(プレーンテキスト)をメールのサブスクリプションへ、https の本文(カスタム通知の JSON)を Amazon Q Developer へ送り、Amazon Q Developer が Slack チャンネルに投稿する。アラームは Amazon Q Developer 自身が整形する。Amazon Q Developer に届いたプレーンテキストは捨てられ、Event received is not supported とログに残るだけになる。アプリのコードpublish_notice()MessageStructure=jsonCloudWatch アラームアラームの状態変化SNS トピックメールのサブスクリプションプレーンテキストdefaultAmazon Q Developerカスタム通知の JSON か、アラームなら自分で整形httpsSlack チャンネルhttps 側に届いたプレーンテキストは捨てられ、us-east-1 のログにだけ残るEvent received is not supported
1 通の SNS メッセージが、メールにはプレーンテキストとして、Amazon Q Developer にはカスタム通知の JSON として届く。Amazon Q Developer に送ったプレーンテキストは捨てられる。

https キーの本文は、Amazon Q Developer に限らず HTTPS のサブスクライバーすべてに届きます。 今のところ HTTPS のサブスクライバーは Amazon Q Developer だけです。 あとから同じトピックに Webhook をサブスクライブすると、その Webhook にもカスタム通知の JSON が届きます。そのため、https キーの横に、この点を注意するコメントを残しました。

1 つの Notice を、メール用と Slack 用に書き分ける

パイプラインでアラートを publish する箇所は、大きく 2 種類に分けられます。

  1. 試行が 1 回失敗したとき:翻訳などのジョブが失敗し、このあとリトライされる場合です。
  2. リトライを使い切ったとき:ジョブがリトライを使い切ってデッドレターキューに入り、その通知処理がアラートを出します。

私はどの箇所でも Notice を 1 つ組み立て、publish_notice() に渡すようにしました。publish_notice() はその Notice を、メール用と Slack 用の 2 通りに書き分けます。

notifier.py
@dataclass(frozen=True)
class Notice:
title: str # デプロイ名
label: str # "Translation failed"
lead: str
severity: Severity = "warning"
target: str = "" # メールの件名だけ
fields: tuple = () # メールと Slack
email_fields: tuple = () # メールだけ
notes: str = ""
blocks: tuple = () # メールと Slack
email_blocks: tuple = () # メールだけ
next_steps: tuple = ()
thread_id: str = ""

ファイル名を Slack に出さない

ファイル名と、ファイルの中から取り出したものは、すべてメールにとどめます。 このプロジェクトでは、ファイル名とファイルの内容を Slack に送らないと決めています。

Notice には、メールでしか使わないフィールドが 3 つあります。

  1. target:メールの件名にだけ出る文字列。ファイル名など。
  2. email_fields:メール本文にだけ出る「名前:値」の項目。「ファイル:report_v2.docx」など。
  3. email_blocks:メール本文にだけ出るまとまったテキスト。スプレッドシートの列見出しや元のキューメッセージなど。

slack_notice() はこの 3 つを読まないので、これらの情報は Slack に出ません。省いた情報がある場合は、Slack のメッセージの最後に、詳細はメールにあると一行添えます。

1 つの Notice を、メール用と Slack 用に書き分ける2 枚のカードが左右に並ぶ。メールのカードには、ファイル名付きの件名、冒頭の文、サービス・ファイル ID・ジョブ ID・ファイル名の項目、理由、次の対応が載る。Slack のカードには、絵文字付きでファイル名の無い見出し、同じ冒頭の文、インラインコードにしたサービス・ファイル ID・ジョブ ID、コードブロックにした理由、ファイル名などはメールにあるという一文、Next steps の下の次の対応が載る。件名とファイル名の項目には、メールだけと印が付く。メール件名[prod] 翻訳失敗: report_v2.docx翻訳処理が失敗しました。サービス: boxファイルID: 123456ジョブID: j-1ファイル: report_v2.docx理由:item_name_in_use (409)対応:- ログをジョブ ID で検索するSlack❌ [prod] 翻訳失敗翻訳処理が失敗しました。サービス:boxファイルID:123456ジョブID:j-1理由item_name_in_use (409)ファイル名などはメールの通知にあります。Next steps:• ログをジョブ ID で検索するメールだけ
同じ Notice をメールと Slack のメッセージにしたもの。件名とファイル名の行はメールにしか無い。

next_steps はカスタム形式の nextSteps に対応し、Slack では「Next steps:」というラベルの下に箇条書きで表示されます。 severity は Slack のタイトルの絵文字を決めます。1 回の試行が失敗しただけなら ❌、リトライを使い切ったジョブなら 🚨 になります。

threadId で、1 つのファイルの失敗を 1 日 1 つのスレッドにまとめる

thread_id は metadata.threadId に対応します。Amazon Q Developer は、以前と同じ ID のメッセージが届くと、それをスレッドへの返信として投稿します。 私はジョブのキーをこの ID に使っています(box#123456 のように、元のサービスとファイル ID からできています)。そのため、あるファイルの試行ごとの失敗と、デッドレターキューの通知が 1 つのスレッドにまとまります。

Amazon Q Developer は、既定では 2 日以内に届いた同じ ID のメッセージを 1 つのスレッドにまとめます。そこで slack_notice() で、Slack のスレッド ID の末尾に日本時間の日付を付けるようにしました。こうすると、翌日に同じ失敗が再発したときは新しいスレッドが始まります。

notifier.py
payload["metadata"] = {
"threadId": f"{notice.thread_id}#{_today()}", # box#123456#2026-11-05
"summary": _slack_escape(notice.heading),
}

summary は、返信が届いたときに Amazon Q Developer がスレッドの最初のメッセージに Latest Update として追加する行です。これで、スレッドを開かなくてもチャンネル上で最新の状態がわかります。

Amazon Q Developer が投稿した Slack のスレッド。最初のメッセージは赤いバツ印と「[prod] Translation failed」というタイトルで、「[prod] Translation failed (retries used up)」と書かれた Latest Update の行、インラインコードで表示されたサービス・ファイル ID・ジョブ ID、コードブロックで表示された理由、Next steps の箇条書きが並ぶ。1 件だけある返信はサイレンと「[prod] Translation failed (retries used up)」というタイトルで、同じファイル ID、トリガー、時刻、返信自身の次の対応が並ぶ。最初のメッセージは「Custom notification delivered by Amazon Q Developer」というフッターで終わる。どちらにもファイル名は出ていない。

あるファイルの試行ごとの失敗とデッドレターキューの通知が、1 つのスレッドにまとまっている。どちらにもファイル名は無い。通知のラベルは英語で、Slack 自体の画面は日本語になっている。

Slack 独自の mrkdwn 記法に対応する

textType: "client-markdown" は、title と description のテキストが Slack の mrkdwn であることを Amazon Q Developer に伝えます。mrkdwn は Slack 独自のマークアップで、*太字* や _斜体_ のように書式を付けます。

Slack の API で直接投稿するなら、plain_text のテキストオブジェクトや mrkdwn: false で書式を無効にできます。しかし Amazon Q Developer のカスタム通知の形式には対応するフィールドが無いので、無効にできません。

title と description の、送った形と表示された形左は送ったカスタム通知の JSON。textType は client-markdown、title は Translation failed、description は File: report *v2* final.docx。Amazon Q Developer から Slack へという矢印の先、右は表示された Slack のメッセージで、太字のタイトル Translation failed の下にある File: report v2 final.docx の v2 が太字になり、アスタリスクが消えている。注記には、mrkdwn は *v2* を太字として読み、アスタリスクとアンダースコアのエスケープが無いとある。Amazon Q Developer → Slackカスタム通知の JSON(送ったもの)"textType": "client-markdown","title": "Translation failed","description":"File: report *v2* final.docx"Slack のメッセージ(表示されたもの)Translation failedFile: report v2 final.docxmrkdwn は *v2* を太字として読み、* と _ のエスケープが無い
ファイル名の *v2* は、Amazon Q Developer を経て Slack に届くとアスタリスクが消え、v2 が太字になる。

値はすべてバッククォートで囲み、Slack でインラインコードかコードブロックとして表示させます。どちらの中でも mrkdwn は効きません。 fields はインラインコードとして、blocks はコードブロックとして表示されます。

それでも &、<、> の 3 つはバッククォートの中でもエスケープします。Slack はこの 3 文字をリンクやメンション(<@U123> など)の記法に使っていて、インラインコードやコードブロックの中でも例外ではないからです。そこで、これを処理する関数を 2 つ書きました。

notifier.py
def _inline_code(value: str) -> str:
# 改行は空白に、バッククォートは ' に置き換え、コードスパンが途中で閉じないようにする。空の値は - にする
text = " ".join(value.split()).replace("`", "'") or "-"
return f"`{_slack_escape(text)}`"
def _slack_escape(text: str) -> str:
return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")

空の値は - にします。空のバッククォートの組は Slack で何も表示されず、メッセージが壊れているように見えるからです。

Job ID が空文字列のとき
そのまま: *Job ID*: ``
Slack: Job ID: // 後ろに何も無い
- に置き換え:*Job ID*: `-`
Slack: Job ID: - // - がインラインコードの枠に入る

コードブロックの中では、値にバッククォートが 3 つ続いているとブロックが途中で終わってしまうので、シングルクォート 3 つに置き換えます。

カスタム形式の description の上限は 8,000 文字です。エスケープすると値は最大で 5 倍に膨らむ(& が &amp; になる)ので、各コードブロックはエスケープしたあとで 2,000 文字以内に切り詰めます。切り詰めたブロックの後ろには、メールを参照するよう促す一行を添えます。 メールには常に全文が載ります。

まとめ

パイプラインのエラーアラートは、メールに加えて Slack にも届くようになりました。どのアラートの送信元も、Publish の呼び出しは 1 回のままです。

  • CloudWatch アラームのように Amazon Q Developer が対応している AWS のイベント以外は、カスタム通知の JSON で送ります。プレーンテキストは捨てられ、us-east-1 のログに Event received is not supported が残るだけです。
  • MessageStructure=json を使うと、サブスクリプションのプロトコルごとに本文を分けられます。default でメールにプレーンテキストを、https で Amazon Q Developer に JSON を届けます。
  • アラートは Notice として 1 回だけ組み立て、publish_notice() でメール用と Slack 用に書き分けます。ファイル名やファイルの内容はメール専用のフィールドに入れるので、Slack には出ません。
  • mrkdwn には _ と * のエスケープが無いので、Slack のメッセージに入れる値はすべてバッククォートで囲みます。ただし &、<、> はバッククォートの中でも Slack が記法として読むので、別にエスケープします。
  • スレッド ID に日付を入れると、1 つのファイルの失敗が 1 日のあいだ同じスレッドにまとまり、失敗が再発した日には新しいスレッドが始まります。
  • ログレベルを ERROR にしておくと、メッセージ本文が us-east-1 のロググループに残りません。

参考リンク

この記事をシェア