設定 Slack 通知
Excubius 會在 Slack 中發出警報通知:警報開啟時、嚴重程度上升時,以及警報解決時。你可以按實體選擇頻道,其下的每個實體都會繼承這些頻道,直到它設定自己的頻道為止。本指南說明如何一次性連接 Slack 應用程式、為實體新增頻道、測試頻道,以及訊息如何路由。
開始之前
- 若要新增頻道,你需要在該實體上具備 Entity admin 角色。
- 若要建立 Slack 應用程式,你需要有權在 Slack 工作區中安裝應用程式。
- 若要把應用程式的權杖提供給 Excubius,你需要能夠存取伺服器:在伺服器上具備
sudo權限,或持有安裝程式套件。
連接 Slack 應用程式
每次安裝只需要執行一次。
-
前往
https://api.slack.com/apps,選取 Create New App,選擇 From scratch,為它取一個團隊容易辨認的名稱,並選擇你的工作區。 -
在 OAuth & Permissions 下,新增機器人權杖範圍
chat:write。Excubius 不需要其他範圍。 -
選取 Install to Workspace 並允許。複製以
xoxb-開頭的 Bot User OAuth Token。 -
在伺服器上,以
sudo -iu excubius切換為服務帳戶,並在/opt/excubius/.env中設定權杖:SLACK_BOT_TOKEN=xoxb-…SLACK_DEFAULT_CHANNEL=#alertsSLACK_DEFAULT_CHANNEL會接收所有「在其上層任何位置都沒有自己頻道」的實體的警告及嚴重警報。省略時預設為#alerts。 -
重新啟動平台:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
安裝程式也會詢問 Slack 機器人權杖及預設頻道;sudo ./install.sh --reconfigure 會再次詢問。在設定權杖之前,Settings › Notifications 會顯示 Slack is not configured on the server,而且不會傳送任何訊息。
為實體新增頻道
- 在 Slack 中,開啟頻道(例如
#ciguapa-alerts),並邀請應用程式加入,例如使用/invite @Monitoring。應用程式只能在它所屬的頻道中發佈訊息。 - 在 Excubius 中,開啟 Settings › Notifications,並在選擇器中選擇實體,例如桃花島物流。
- 選取 Add Slack channel。
- 填寫欄位:
- Name:給你的團隊使用的名稱,例如桃花島警報。
- Slack channel:小寫的
#name,或頻道 ID,例如C0123456789。 - Minimum:發佈的最低嚴重程度,即 Info、Warning 或 Critical。低於此程度的警報不會發佈。
- Message language:English 或 Español。西班牙文需要功能
ui.i18n;沒有該功能時,欄位會說明訊息使用英文。
- 選取 Add Slack channel。
- 在新頻道上選取 Test。
Slack 頻道中會出現一則測試訊息,而 Excubius 會顯示 Test message sent。如果 Slack 拒絕該訊息,錯誤會指出原因,例如 not_in_channel:請邀請應用程式加入頻道、檢查頻道名稱,然後再次測試。
來自桃花島物流及其下所有項目的警報,現在都會傳送到該頻道。一個實體可以有多個頻道,例如一個用於警告,另一個只用於嚴重警報。
關閉、變更或移除頻道
在頻道的列上:
- 使用其開關可以關閉頻道而不移除它,之後可再開啟。當實體的所有頻道都關閉時,該實體會使用從上層繼承的頻道。
- 選取 Edit 可以變更任何欄位,然後選取 Save。
- 選取 Remove 可以停止向它傳送。頻道本身仍保留在 Slack 中。
訊息如何找到它的頻道
頁面會在 Where alerts go 之下顯示所選實體的結果:它自己的頻道,或繼承而來的頻道及其來源實體,或伺服器的預設頻道。
| 情況 | 警報的去向 |
|---|---|
| 警報所屬的實體有已啟用的頻道 | 它自己的頻道,每個頻道各自以其 Minimum 篩選 |
| 它沒有頻道,但上層實體有 | 最近一個有頻道的上層實體的頻道 |
| 路徑上沒有任何實體有頻道 | SLACK_DEFAULT_CHANNEL,只傳送警告及嚴重警報 |
| 沒有頻道,也沒有預設頻道 | 不會傳送到任何地方;頁面會說明這一點 |
每則訊息都包含資源及其實體路徑、檢查、數值與閾值的比較及該閾值的設定位置、狀況已持續多久、檢查目錄中有的話則附上建議的處理方式,以及警報的連結。訊息從不提及產品名稱。
讓頻道保持安靜的機制:
- 每個狀況一個警報。 重複出現只會更新警報,不會傳送任何訊息。
- 靜默期。 除非嚴重程度上升,否則每個狀況每 10 分鐘最多傳送一則訊息。伺服器設定
EXCUBIUS_NOTIFY_QUIET_MINUTES可以變更這段時間。 - 根本原因。 當資源無法連線時,只會傳送一個嚴重的 Cannot reach 警報,該資源的其他警報會等到它解決後才傳送。
- 靜音及維護時段。 在它們持續期間不會傳送任何訊息;頻道尚未收到的內容,會在它們結束時發出(如果仍然適用)。
- 不發送降級通知。 從嚴重降為警告只會記錄在警報的時間軸中,不會傳送。只有在開啟時已傳送通知,才會傳送解決通知。
- 已關閉的功能。 功能已關閉的模組所產生的警報永遠不會傳送,安全建議也一樣。
Slack 絕不會妨礙監控:結果會先儲存並評估,訊息隨後才會發出,並由每 15 秒一次的背景掃描發出。傳送失敗會記錄在警報的時間軸中,並由之後的掃描重試,合共三次嘗試。
使用 API 操作
| 工作 | 要求 |
|---|---|
| 查看實體的頻道及其有效路由 | GET /api/v1/entities/{id}/channels |
| 新增頻道 | POST /api/v1/entities/{id}/channels |
| 變更、關閉或開啟 | PATCH /api/v1/channels/{id},可帶有 name、config、min_severity、locale、enabled 的任何一項 |
| 移除 | DELETE /api/v1/channels/{id} |
| 傳送測試訊息 | POST /api/v1/channels/{id}/test。回應 {"ok": true},或回應 {"ok": false, "error": "not_in_channel"} 並附上 Slack 提供的原因 |
curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/channels" -d '{
"kind": "slack", "name": "Ciguapa alerts", "config": {"channel": "#ciguapa-alerts"},
"min_severity": "warning", "locale": "es"
}'