Интеграция Zabbix и ПланФикс: жизненный цикл задачи из алерта мониторинга

Связали Zabbix 7.0 (около 260 хостов) с таск-трекером ПланФикс так, что событие мониторинга автоматически проходит весь жизненный цикл задачи: проблема создаёт задачу, нажатие Acknowledge переводит её «В работе», восстановление триггера закрывает, отмена эскалации отменяет.

Всё держится на штатном механизме Zabbix: media type типа Webhook (скрипт на JavaScript) и действия с эскалацией, без промежуточного сервиса и внешней базы соответствий. Ниже разбираем архитектуру, полный код webhook на JavaScript и тонкости настройки медиатипа, которые экономят часы при переносе на свою инсталляцию.

Интеграция Zabbix и ПланФикс закрывает разрыв между мониторингом и учётом работ: пока проблема видна только в Zabbix, задача для дежурной смены заводится в ПланФикс руками. На наших проектах это означало потерянные инциденты, отсутствие истории «проблема ↔ задача» и ручную рутину на каждом срабатывании триггера.

Дано: боевая инсталляция Zabbix 7.0, около 260 хостов разных клиентов и порядка 150 шаблонов. Заявки и работа дежурных у нас ведутся в ПланФикс, поэтому именно туда должны попадать значимые события мониторинга. До автоматизации связка держалась на внимательности оператора: увидел алерт, скопировал, создал задачу, не забыл закрыть. На потоке из сотен хостов такая схема даёт сбои ежедневно.

Мы поставили цель: двусторонняя автоматическая связка «проблема Zabbix ↔ задача ПланФикс» без ручного труда и без отдельного промежуточного сервиса. Принципиальное ограничение: никаких внешних демонов и сторонних шин, только то, что умеет сам Zabbix. Любой дополнительный сервис пришлось бы мониторить отдельно, а это новая точка отказа в системе, которая как раз и следит за отказами.

К решению мы предъявили четыре требования. Во-первых, реакция не на каждый «чих»: проблема, мигнувшая на 30 секунд, не должна плодить задачу. Во-вторых, полный жизненный цикл: создание, перевод в работу, закрытие и отмена. В-третьих, идемпотентность по возможности, чтобы повторная доставка не порождала дубли. В-четвёртых, выборочность: задачи только по значимым проблемам и не по всем группам хостов, потому что часть парка составляют внутренние и партнёрские группы, которым место в трекере не нужно.

Не пытайтесь решить это «уведомлением на почту с парсером»: мы сталкивались с тем, что почтовый канал не возвращает в Zabbix идентификатор задачи, и связать восстановление триггера с конкретной строкой в трекере потом нечем. Именно требование вернуть task id обратно в событие определило всю дальнейшую архитектуру.

Интеграция Zabbix и ПланФикс держится на двух штатных сущностях Zabbix и одном приёме: тип оповещения media type (webhook), действия (actions) с фильтрами и эскалацией, а в роли «памяти» о созданной задаче выступают теги события. Внешней базы соответствий между проблемами и задачами нет, и это сознательное решение.

Поток данных простой. Триггер переходит в проблему, событие попадает в одно из действий (у нас это действия с внутренними номерами 87, 88 и 89), где фильтр проверяет severity, группы хостов и флаг suppressed. Если проблема прожила дольше одного периода эскалации и её не подтвердили, на шаге эскалации 2 операция-сообщение уходит служебному пользователю ПланФикс, а тот доставляет его через media type «Planfix Tasks». Скрипт дёргает эндпоинт zabbix-new, ПланФикс отдаёт task id.

Дальнейшие переходы используют те же теги. Когда триггер возвращается в OK, recovery-операция (тип 11) закрывает задачу; когда инженер нажимает Acknowledge, update-операция (тип 12) переводит её в работу; при отмене эскалации уведомление приходит благодаря notify_if_canceled. Во всех случаях скрипт берёт taskId из тега, а не из внешнего справочника. Для удобства дежурного включён show_event_menu: прямо из карточки проблемы в Zabbix открывается связанная задача по ссылке __zbx_planfix_link. Подробности механизма — в документации Zabbix: media type webhook и действия и эскалации.

Ключевая идея — теги как память. При создании задачи webhook-скрипт возвращает Zabbix два тега: __zbx_planfix_taskid с идентификатором задачи и __zbx_planfix_link со ссылкой на неё, прикрепляет их к событию (process_tags=1), и все последующие операции (закрытие, acknowledge, отмена) находят ту же задачу по этим тегам — внешняя СУБД соответствий не нужна. Вот что скрипт отдаёт обратно в Zabbix:

Вся интеграция Zabbix и ПланФикс собирается из штатных средств Zabbix — отдельный сервис не нужен. Ниже порядок настройки от media type до действий; полный код скрипта приведён отдельным блоком ниже.

Шаг 1. Создайте media type. В Zabbix откройте Оповещения → Способы оповещений → Создать способ оповещения, тип — Webhook, имя — например «Planfix Tasks». Это контейнер для скрипта, параметров и шаблонов сообщений.

Шаг 2. Вставьте webhook-скрипт в поле Скрипт — полный код в разделе «Полный код webhook-скрипта» ниже. Скрипт получает все данные события одним JSON в переменной value и сам собирает HTTP-запрос к ПланФикс.

Шаг 3. Задайте параметры в разделе Параметры — пары «имя → макрос Zabbix». Скрипт читает их из value через JSON.parse(value); адрес ПланФикс и проект тоже передаются параметрами, поэтому код переносится между инсталляциями без правок:

Шаг 4. Настройте шаблоны сообщений для трёх состояний события: проблема (recovery=0), восстановление (recovery=1) и обновление/acknowledge (recovery=2). Без шаблона {ALERT.MESSAGE} придёт пустым и webhook упадёт на валидации. В шаблоне проблемы передайте как минимум {EVENT.NAME}, {HOST.NAME}, {EVENT.SEVERITY}, {EVENT.ID} и ссылку на событие. Acknowledge и его снятие скрипт распознаёт по первой строке шаблона обновления, куда {EVENT.UPDATE.ACTION} разворачивается в acknowledged или unacknowledged.

Шаг 5. Задайте параметры доставки — они определяют порядок и надёжность отправки:

Значение maxsessions=1 принципиально: повышать нельзя, иначе закрытие задачи обгонит её создание и edit придёт по ещё не существующей задаче. Включите также process_tags=1 (скрипт пишет теги обратно в событие) и show_event_menu со ссылкой {EVENT.TAGS.__zbx_planfix_link} — тогда из карточки проблемы в Zabbix открывается связанная задача.

Шаг 6. Поднимите четыре эндпоинта на стороне ПланФикс. Каждый отвечает за свой переход жизненного цикла задачи — их и вызывает скрипт:

На стороне ПланФикс каждый эндпоинт — это входящий вебхук: zabbix-new создаёт задачу из переданных полей (name, description, project) и возвращает {"task": id}; zabbix-edit, zabbix-ack и zabbix-unack находят задачу по параметру task и меняют статус, исполнителя или добавляют комментарий. Поэтому скрипт после создания и сохраняет task id в теге события — чтобы остальные вызовы нашли ту же задачу. Формат входящих запросов — в справке ПланФикс по входящим вебхукам.

Шаг 7. Создайте действия (actions), которые маршрутизируют проблемы в ПланФикс по уровню важности. Три действия с одинаковым фильтром, отличающиеся только severity:

Условия фильтра соединены по AND: совпадение severity, хост не входит в служебные группы ГРУППА-A, ГРУППА-B и ГРУППА-C, проблема не подавлена (не suppressed). Операция-сообщение стоит на шаге эскалации 2 с условием «Event acknowledged = No» — это шумовой фильтр: задача заведётся, только если проблема прожила дольше одного периода эскалации и её не подтвердили. Recovery- и update-операции (тип Notify all involved) обрабатывают восстановление и acknowledge, а notify_if_canceled=1 обязателен, иначе webhook не получит уведомление об отмене эскалации. Все действия шлют сообщения служебному пользователю ПланФикс, у которого единственный канал — этот медиатип.

Шаг 8. Настройте обратный сценарий ПланФикс → Zabbix. Связка двусторонняя: когда оператор принимает задачу в ПланФикс, событие в Zabbix должно подтвердиться (acknowledge) — с ответственным и комментарием. В ПланФикс это автоматический сценарий: событие — «Задача принята»; условия — статус ≠ «Завершенная» и проект = ZABBIX; операция — послать HTTP-запрос POST на адрес вашего Zabbix — https://zabbix.example.com/api_jsonrpc.php (Content-Type: application/json):

{
  "jsonrpc": "2.0",
  "method": "event.acknowledge",
  "params": {
    "eventids": ["{{Задача.Event ID}}"],
    "action": 6,
    "message": "ACK from Planfix by {{Текущий пользователь.ФИО}}"
  },
  "auth": "API_TOKEN",
  "id": 1
}

Здесь action: 6 — битовая маска Zabbix (2 «подтвердить» + 4 «добавить сообщение»): событие переходит в acknowledged и получает комментарий. eventids берётся из поля задачи {{Задача.Event ID}} — того самого event_id, что скрипт передал при создании, поэтому ПланФикс всегда знает, какое именно событие подтверждать. Адрес https://zabbix.example.com/api_jsonrpc.php — это JSON-RPC API вашего сервера Zabbix (подставьте свой хост). В итоге инженер работает там, где удобнее: нажал «принял» в Zabbix — задача в ПланФикс уходит «В работе»; взял задачу в ПланФикс — подтверждается событие в Zabbix. Токен Zabbix API храните в защищённом поле, а не открытым текстом в теле вебхука.

В интеграции Zabbix и ПланФикс полный жизненный цикл задачи означает, что одно событие мониторинга проходит путь от создания до закрытия или отмены без участия человека. Скрипт работает как конечный автомат: по флагам события он определяет тип перехода и выбирает нужный эндпоинт. Порядок проверки веток важен, и отмена эскалации проверяется первой — почему именно так, видно из кода диспетчера ниже.

Разберём типовой сценарий. Триггер сработал, проблема прожила дольше одного периода эскалации, на шаге 2 уходит оповещение. Скрипт видит event_value=1 и event_update_status=0, попадает в ветку новой проблемы и вызывает zabbix-new. ПланФикс создаёт задачу и возвращает её идентификатор, который скрипт кладёт в теги события. С этого момента задача и проблема связаны.

Дальше инженер берёт проблему в работу и нажимает Acknowledge. Приходит обновление, первая строка которого содержит acknowledged, скрипт вызывает zabbix-ack, передаёт исполнителя и переводит задачу в статус «В работе». Если acknowledge сняли, отрабатывает zabbix-unack и исполнитель возвращается к значению по умолчанию (у нас это группа сотрудников техподдержки).

Когда триггер восстанавливается, событие приходит с event_value=0, скрипт распознаёт восстановление и через zabbix-edit переводит задачу в «Завершенная». Отдельный случай — отмена эскалации: проблема ещё активна, но эскалацию погасили, отключив хост или триггер. Такое событие маскируется под новую проблему, поэтому его проверка стоит первой, и задача уходит в «Отмененная», а не дублируется.

Везде, кроме создания, скрипт берёт идентификатор задачи из тега __zbx_planfix_taskid. Если тега нет (например, проблема случилась раньше, чем мы развернули интеграцию), ветка молча завершается без вызова ПланФикс: закрывать или комментировать нечего. На наших проектах это спасает от ошибок на «исторических» событиях, которые ещё живут в системе после включения связки.

Скрипт целиком — три логические части в одном файле: объект Planfix (валидация параметров и четыре метода-обёртки над эндпоинтами), helper clean() для очистки значений и блок MAIN с конечным автоматом, который по флагам события выбирает нужную ветку. В движке Zabbix всё это исполняется как единый скрипт, поэтому приводим его одним блоком.

Куда вставить: в Zabbix откройте Оповещения → Способы оповещений, создайте media type типа Webhook и вставьте код в поле Скрипт. Параметры из таблицы выше добавьте в разделе Параметры того же медиатипа — скрипт читает их из value через JSON.parse(value).

Вся схема работает на штатных средствах Zabbix 7.0, без промежуточного сервиса; перенос на другую инсталляцию — это правка макросов медиатипа и четырёх эндпоинтов на стороне ПланФикс. Финальный чек-лист, собранный из того, что мы переписывали по ходу проекта:

• Media type = Webhook: скрипт-автомат на JavaScript, статусы ПланФикс вынесены в переменные.
• Теги события как память: возвращайте __zbx_* теги при создании и ищите задачу по ним в остальных ветках; включите process_tags=1 и show_event_menu для ссылки из карточки.
• Шумовой фильтр через эскалацию: операция создания на шаге не ниже 2 плюс условие «Event acknowledged = No», чтобы короткие мигания и быстро подтверждённые проблемы не плодили задачи.
• Шаблоны для всех состояний: problem, recovery и update, иначе пустой {ALERT.MESSAGE} уронит webhook.
• Отмена эскалации первой веткой: notify_if_canceled=1 плюс отдельная проверка баннера до восстановления.
• Порядок против дублей: maxsessions=1, а повторы включайте только при идемпотентном создании с дедупликацией по event_id на приёмнике.
• Исключайте служебные группы из маршрутизации и фильтруйте suppressed.
• Сервисный пользователь с единственным каналом даёт чистую схему «действие → пользователь → media type».
• Проверяйте доставку по каждому действию отдельно, а не по факту «что-то приходит»: иначе легко не заметить, что целый класс алертов (например, disaster) вообще не доходит до трекера.

И последнее — перед первым реальным алертом проверьте эндпоинт вручную, одним запросом curl, имитирующим zabbix-new. Если в ответе нет поля task, скрипт намеренно бросит исключение, поэтому такую проверку стоит сделать заранее:

Ответы на часто задаваемые вопросы по теме статьи.

Константин Тютюнник — ведущий инженер IT For Prof. Специализируется на системах мониторинга и автоматизации IT-процессов: внедрение Zabbix, интеграции с таск-трекерами, webhook-автоматизация инцидентов.