Настройка уведомлений 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 и разрешите установку. Скопируйте Bot User OAuth Token — он начинается с
xoxb-. -
На сервере переключитесь на учетную запись службы командой
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в нижнем регистре или идентификатор канала, например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"
}'