我用 Amazon Q Developer 把 SNS 警報送進 Slack — 只發布一則 SNS 訊息,依訂閱協定送出不同的內容

Amazon Q Developer 會丟棄純文字的 SNS 訊息。發布時加上 MessageStructure=json,同一則訊息就能讓電子郵件收到純文字、讓 Slack 收到自訂通知。

白色卡片中央的 Slack 標誌:由藍、綠、紅、黃四色圓角長條組成的井字形標記,旁邊是黑色的 slack 字樣,下方有小小的藍色雲朵與 from Salesforce 字樣
本頁目錄

引言

我在 AWS 上運行一個文件翻譯工作流,目前每一則警報是以 SNS 電子郵件寄來,但我打算同時讓它將錯誤警報也送到團隊的 Slack 頻道上。 Amazon Q Developer in chat applications(前身為 AWS Chatbot)不必寫程式就能把 SNS 主題接到 Slack 上。所以在導入 production 環境之前,我先在自己的工作區試了一次。

CloudWatch 警示順利送到了 Slack,但我自己的程式發布的訊息全都被默默丟棄了。這是因為 Amazon Q Developer 只接受它自訂的通知 JSON。

解決方法是發布時加上 MessageStructure=json,只發布一則 SNS 訊息,就能讓電子郵件收到純文字的內容,讓 Slack 收到自訂通知的 JSON。 每個警報來源依然只呼叫一次 Publish,CloudWatch 警示送到 Slack 的方式也完全不受影響。

警報如何送到 Slack?

Amazon Q Developer in chat applications 以頻道組態(channel configuration)為單位設定。一個頻道組態包含三樣東西:

  1. Slack 頻道:接收警報的頻道,一個頻道組態只對應一個頻道。
  2. SNS 主題:負責把通知送進這個頻道的主題,可以指定多個。
  3. IAM role:在頻道裡輸入的指令會以這個 role 的身分執行。

建立頻道組態後,Amazon Q Developer 會以 HTTPS 訂閱每一個主題。主題原本的電子郵件訂閱則維持不變。

有兩個步驟仍然需要手動完成:

  1. 核准 AWS 應用程式:要由能存取該 Slack 工作區的人在 OAuth 畫面上核准。這個畫面要從 Amazon Q Developer 主控台開啟,而這個主控台只能在美國東部(俄亥俄)使用。
  2. 邀請到私人頻道:如果是私人頻道,還要在該頻道輸入 /invite @Amazon Q,否則私人頻道什麼都收不到。

其餘的部分全都可以用 CDK 完成。 aws-cdk-lib/aws-chatbot 的 SlackChannelConfiguration 有一個可省略的 role 屬性。下面的程式碼沒有指定 role,所以 CDK 會自動建立一個只有 trust policy、沒有任何權限的 role。我另外把 ReadOnlyAccess 設為 guardrail。guardrail 是一種 IAM 政策,不論 role 有什麼權限,頻道裡的指令最多只能做到 guardrail 允許的範圍。

這個頻道只負責接收警報。即使在頻道裡對 @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,
});

這個 stack 位於東京區域。雖然 Amazon Q Developer 主控台只能在俄亥俄使用,頻道組態還是可以直接從東京的 stack 部署,不需要另外建立美國區域的 stack。

為什麼純文字的 SNS 訊息送不到 Slack?

Amazon Q Developer 會丟棄純文字的 SNS 訊息,而且只會留下一行日誌:

/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 會自行排版它支援的 AWS 服務通知,例如 CloudWatch 警示。其他訊息則必須使用自訂通知格式。 自訂通知是一個 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」,而這個格式沒有任何欄位能移除它。

一則 SNS 訊息,依訂閱協定送出不同的內容

MessageStructure=json 能讓一次 Publish 呼叫為每一種訂閱協定送出不同的內容。 這時 Message 會變成一個 JSON 物件,key 是協定名稱,值是字串。 default 是必填的,會用於所有沒有專屬 key 的協定。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,所以會被編碼兩次。 電子郵件和以前一樣,收到 default 的內容和 Subject。

一則 SNS 訊息,依訂閱協定送出不同的內容應用程式的程式碼以 MessageStructure=json 呼叫一次 Publish,CloudWatch 警示也發布到同一個 SNS 主題。主題把 default 的內容(純文字)送給電子郵件訂閱,把 https 的內容(自訂通知的 JSON)送給 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
一則 SNS 訊息以純文字送到電子郵件,以自訂通知的 JSON 送到 Amazon Q Developer。送到 Amazon Q Developer 的純文字只會被丟棄。

https key 的內容會送到每一個 HTTPS 訂閱者,並不只是 Amazon Q Developer。 目前唯一的 HTTPS 訂閱者是 Amazon Q Developer。 如果之後有 Webhook 訂閱了同一個主題,這個 Webhook 也會收到自訂通知的 JSON,所以我在 https key 旁邊留了一行註解提醒這件事。

同一個 Notice,分別產生電子郵件與 Slack 的版本

工作流裡會發布警報的地方,主要分成兩類:

  1. 單次嘗試失敗:翻譯之類的工作執行失敗,但之後還會重試。
  2. 重試次數用盡:工作用完了重試次數、進入 dead-letter queue,由通知程式發出警報。

我讓這些地方都先建立一個 Notice,再交給 publish_notice(),由它把同一個 Notice 產生成電子郵件和 Slack 兩個版本。

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 有三個只給電子郵件用的欄位:

  1. target:只出現在電子郵件主旨裡的文字,例如檔名。
  2. email_fields:只出現在電子郵件內文裡的「名稱:值」,例如「檔案:report_v2.docx」。
  3. email_blocks:只出現在電子郵件內文裡的整段文字,例如試算表的欄位標題或原始的佇列訊息。

slack_notice() 不讀這三個欄位,所以這些資訊不會出現在 Slack。如果有資訊因此被省略,Slack 訊息最後會加上一行,說明細節請見電子郵件。

同一個 Notice,分別產生電子郵件與 Slack 的版本兩張卡片左右並排。左邊是電子郵件:主旨含檔名,接著是開頭的句子,服務、檔案 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 標題裡的表情符號。單次嘗試失敗時顯示 ❌,用完重試次數的翻譯工作則顯示 🚨。

用 threadId 把同一個檔案當天的失敗歸進同一個討論串

thread_id 對應到 metadata.threadId。當訊息帶著 Amazon Q Developer 先前收過的 ID 時,Amazon Q Developer 會把這則訊息張貼成討論串裡的回覆。 我用翻譯工作的 key 作為 ID(例如 box#123456,由來源服務和檔案 ID 組成),所以同一個檔案每次嘗試的失敗和當次的 dead-letter 通知,都會集中在同一個討論串裡。

Amazon Q Developer 預設會把 2 天內 ID 相同的訊息歸進同一個討論串。所以我讓 slack_notice() 在 Slack 討論串 ID 後面加上日本時間的日期。這樣一來,如果同樣的失敗隔天又發生,就會開啟一個新的討論串:

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

回覆送達時,Amazon Q Developer 會把 summary 以 Latest Update 的形式加在討論串第一則訊息上,這樣不必打開討論串,也能在頻道上看到最新狀態。

Amazon Q Developer 張貼的 Slack 討論串。第一則訊息的標題是紅色叉號加上「[prod] Translation failed」,下面依序是寫著「[prod] Translation failed (retries used up)」的 Latest Update 一行、以行內程式碼呈現的服務、檔案 ID 與工作 ID、以程式碼區塊呈現的原因,以及一個 Next steps 項目。唯一的一則回覆以警笛和「[prod] Translation failed (retries used up)」為標題,列出同一個檔案 ID、觸發事件、時間,以及它自己的下一步。第一則訊息以「Custom notification delivered by Amazon Q Developer」頁尾結束。兩則訊息都沒有出現檔名。

同一個檔案每次嘗試的失敗和當次的 dead-letter 通知集中在同一個討論串,兩則都沒有出現檔名。通知的標籤是英文,Slack 本身的介面是日文。

對應 Slack 特有的 mrkdwn 語法

textType: "client-markdown" 告訴 Amazon Q Developer,title 和 description 裡的文字是 Slack 的 mrkdwn。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 則顯示成程式碼區塊。

但即使包在反引號裡,&、< 和 > 還是要跳脫,因為 Slack 用這三個字元來標記連結和提及(例如 <@U123>),即使在程式碼或程式碼區塊裡也不例外。因此我寫了兩個函式來處理這些情況:

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: - // - 顯示在行內程式碼框裡

在程式碼區塊裡,值裡面如果有三個連續的反引號,區塊就會提前結束,所以會換成三個單引號。

自訂格式的 description 上限是 8,000 個字元。由於跳脫後的值最長可能會膨脹為原本的五倍(& 會變成 &amp;),所以每個程式碼區塊會在跳脫之後截斷到 2,000 個字元以內。被截斷的區塊後面會加上一行提示,請讀者參閱電子郵件。 電子郵件裡永遠是完整的內容。

總結

工作流的錯誤警報現在除了電子郵件,也會送到 Slack,而每個警報來源依然只呼叫一次 Publish。

  • 除了 CloudWatch 警示這類 Amazon Q Developer 支援的 AWS 事件,其他訊息都要用它的自訂通知 JSON 送出。純文字訊息會被丟棄,只會在 us-east-1 的日誌裡留下 Event received is not supported。
  • MessageStructure=json 能讓每一種訂閱協定收到各自的內容。default 把純文字送到電子郵件,https 把 JSON 送到 Amazon Q Developer。
  • 每則警報先建立一個 Notice,再由 publish_notice() 產生電子郵件和 Slack 兩個版本。檔名和檔案內容放在只給電子郵件用的欄位,就不會出現在 Slack。
  • mrkdwn 沒有 _ 和 * 的跳脫方式,所以 Slack 訊息裡的每個值都用反引號包起來。然而 &、< 和 > 在反引號裡依然會被 Slack 當成標記,所以要另外跳脫。
  • 在討論串 ID 裡加上日期,就能讓同一個檔案在一天內的失敗集中在一個討論串,並在失敗再次發生的那天開一個新的討論串。
  • 把日誌層級設為 ERROR,訊息內容就不會留在 us-east-1 的日誌群組裡。

參考連結

分享這篇文章