Telegram в России очень популярен и неудивительно, что даже не смотря на его блокировки многие админы или девопсы все также продолжают рассматривать этот сервис как основу для получения нотификаций из систем мониторинг. Zabbix тут не исключение.
Телеграм-канал автора Егорыч поясняет за AI Помогаю кожаным и AI жить в любви и понимании — шутим, даём советы, рефлексируем. ПодписатьсяУведомления Zabbix в Telegram
Нюанс в том, что в Zabbix нет нативной поддержки Телеграм и для его использования необходимо настраивать вебхуки, при конфигурировании которых можно допустить огромное количество ошибок, из-за которых совершенно молча вы будете пропускать критические уведомления. Вот эти кейсы сейчас и разберем.
Принцип работы оповещений в Zabbix
Чтобы уведомление дошло до нужного человека, в Zabbix должны совпасть три настройки.
- Media type — способ отправки (Email, Script или Webhook). Telegram использует Webhook.
- Media у пользователя — адрес доставки. Здесь указывается chat id, важность (severity), при которой этот адрес используется, и часы, когда он активен.
- Action — правило «когда и кому». Условия (например, хост или важность триггера), шаги эскалации, а также отдельные сообщения о восстановлении и об обновлении проблемы.
Webhook в Zabbix под капотом работает на базе JavaScript. Перед запуском скрипта в него подставляются значения макросов вроде {EVENT.NAME} и {ALERT.SENDTO}. Скрипт выбирает адрес и содержимое сообщения. Если он возвращает результат, Zabbix считает отправку успешной; если выбрасывает исключение, записывает ошибку.
Настройка уведомлений Telegram
А теперь бегло вспомним как настраивать связку Zabbix + Telegram, погнали.
1. Бот
В Telegram откройте @BotFather, отправьте /newbot и пройдите диалог. BotFather выдаст токен вида 1234567890:AA…. Скопируйте, он понадобится далее.
2. Токен в media type
В Zabbix уже есть готовый media type Telegram. Откройте Alerts / Media types / Telegram, впишите токен в параметр api_token и переключите media type в Enabled. Готовые шаблоны из коробки выключены. Параметр api_parse_mode содержит заглушку <PLACE PARSE MODE>. С ней сообщения уходят простым текстом, что помогает избежать ошибки форматирования, описанной ниже.
3. Chat id
Бот не может написать человеку первым. Для личного чата сначала откройте своего бота и нажмите Start. Узнать chat id можно двумя способами:
- вызвать getUpdates после того, как вы написали боту (или добавили его в группу), и найти в ответе chat.id:
|
1 |
curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[].message.chat' |
- либо спросить у вспомогательного бота @userinfobot, он вернёт ваш личный id. В случае с группой вам придется временно добавить его туда.
Личный id положительный, у групп id отрицательный (например -5450729185).
4. Media у пользователя
Откройте Users / Users, создайте пользователя, например tg-oncall. Откройте его и пройдите Media / Add, выберите Type Telegram и вставьте chat id в Send to. В When active укажите часы доставки, а в Use if severity нужные важности (я бы оставил только High и Disaster, по остальным не знаю зачем уведомления).
5. Action
Откройте Alerts / Actions / Trigger actions / Create action. На вкладке Action задайте условие (например по хостам или по Trigger severity, выбирайте на свой вкус). На вкладке Operations добавьте отправку пользователю tg-oncall через Telegram. Для сообщений о восстановлении заполните Recovery operations. Без них закрывающего события не получите.
Пробная отправка
В списке Alerts / Media types у каждого элемента есть кнопка Test. Нажмите её, введите параметры отправки и ожидайте уведомления. Если здесь возникает ошибка, сначала разберитесь с media type и chat id, затем переходите к action.
Как можно все сломать
Ищите ошибки отправки в Reports / Action log. У неудачной отправки будет статус Failed и текст от Telegram или скрипта. Код ответа и chat id там не указаны, поэтому одинаковая формулировка может скрывать разные причины. Разберем большинство возможных вариантов.
Неверный chat id и группа без минуса
Сообщение chat not found появляется, если chat id неверен или человек не нажал Start у бота.
|
1 |
Sending failed: Bad Request: chat not found |
Засада в том, что тот же ответ Telegram возвращает для группы, когда её id указан без минуса. По одному тексту ошибки эти причины не различить.
Кривой формат chat id
Такую ошибку выдаёт скрипт media type ещё до отправки в Telegram:
|
1 |
Sending failed: Webhook processing failed: Invalid format for api_chat_id: "tg db". Must be a numeric group ID or @GroupName, optionally followed by :message_thread_id. |
Он отклоняет chat id с пробелами, буквами или лишними символами. Допустимы число с минусом или без него, @ИмяГруппы и необязательный номер темы через двоеточие.
HTML parse mode и угловая скобка в имени триггера
При api_parse_mode = HTML символы в имени триггера могут сорвать отправку всего сообщения, получите ошибку:
|
1 |
Sending failed: Bad Request: can't parse entities: Unclosed start tag "b" at byte offset 15 |
Для Markdown и MarkdownV2 скрипт сам экранирует спецсимволы. Подчёркивания, точки, скобки и дефисы в именах хостов отправку не ломают.
А теперь самое важное. Если форматирование не нужно, оставьте parse mode пустым или с заглушкой.
Повторы и обманчивый Sent
По умолчанию Zabbix делает три попытки отправки с интервалом 10 секунд. Постоянную ошибку вроде chat not found он не отличает от временной, поэтому ставит Failed в Reports / Action log только после третьей попытки. В логе сервера на каждую попытку появляется короткая строка без id алерта и chat id:
|
1 |
[Telegram Webhook] notification failed: Bad Request: chat not found |
Статус Sent означает, что Telegram принял сообщение. Детальный разбор работы вебхуков подрбно расписаны в статье как на самом деле работают повторы webhook.
То же самое через Incident Garden
Я пишу свой on-call сервис для дежурных админов, девопсов и SRE, называется Incident Garden. С ним вы можете не париться про доставку в TG — сервис предоставляет это из коробки.
Zabbix и Incident Garden. В команде создаётся интеграция типа Zabbix, а в Zabbix один media type типа Webhook со скриптом и параметрами-макросами. Готовый скрипт и таблица параметров есть в гайде по подключению Zabbix. Action настраивается фактически так же, как выше.
Бот организации. Администратор организации один раз создаёт бота у @BotFather и вставляет токен в карточку Telegram Bot на странице Settings / General. Подробности в гайде по подключению Telegram:
Канал у каждого участника. Каждый дежурный в Settings / Notifications нажимает Add Channel, выбирает Telegram, нажимает Start у бота, вставляет свой Chat ID и подтверждает (статус Verified) канал кодом от бота.
Затем его указывают в правилах уведомлений для critical и warning.
Incident Garden снимает с вас необходимость строить инфраструктуру для отправки сообщений в ТГ, пользуйтесь.
А если Telegram недоступен вовсе
Если все же есть острое желание настроить прямую отправку с Zabbix в ТГ без промежуточных сервисов, то вы точно должны знать как идентифицировать ошибку с таймаутом при блокировке обращений до api.telegram.org. Об этом расскажу в следующей статье.
