Zabbix HTTP agent: ловим ошибки в JSON, когда сайт жив
Москва, Щёлковское шоссе, д. 92, корп. 7 · Пн–Пт 9:00–19:00 · +7 903 729-62-41
АйТи Фреш
Linux, Docker и DevOps

Zabbix без агента: HTTP agent, JSONPath и зависимые элементы для API 1С, сайта и CRM

Автор: , директор ООО «АйТи-Фреш» · · ~17 мин чтения
Схема мониторинга Zabbix HTTP agent с JSONPath: скрытая ошибка в JSON
Видим ошибку там, где обычный мониторинг показывает только зеленый статус.

Если ваш сайт отдаёт статус 200, а корзина пуста или 1С молчит внутри успешного ответа, обычный пинг вас не спасёт. Я покажу, как настроить HTTP agent в Zabbix 7.0, чтобы извлекать данные через JSONPath, проверять бизнес-логику и создавать зависимые элементы из одного ответа. Разберём реальный кейс магазина «Грядка», где мы нашли проблему, скрытую за красивым HTTP-кодом.

Почему HTTP agent лучше простого пинга и веб-сценариев

Классический мониторинг доступности часто сводится к проверке того, что сервер отвечает на ICMP-запросы или отдаёт HTTP 200. Это полезно, но недостаточно для современного бизнеса. Представьте ситуацию: интернет-магазин работает, страница открывается, но API, отвечающий за оформление заказа, возвращает ошибку в теле ответа, которую никто не видит. Именно здесь в игру вступает HTTP agent в Zabbix 7.0. Он позволяет отправлять сложные запросы с заголовками, авторизацией и телом, а затем анализировать полученный ответ не на уровне байтов, а на уровне данных. Это не магия, это инструмент, требующий правильной сборки сервера. Без библиотеки cURL этот тип элементов просто не появится в интерфейсе. Если у вас Zabbix собран без cURL, вы даже не увидите опцию создания HTTP agent. Это фундаментальное требование, которое многие игнорируют, пытаясь натянуть веб-сценарии на задачи, где они не нужны.

В отличие от старых веб-сценариев, которые эмулируют действия браузера и могут быть громоздкими, HTTP agent работает быстрее и гибче благодаря поддержке зависимых элементов. Веб-сценарии хороши для проверки сценариев пользователя, но для мониторинга API они избыточны. Они требуют множества шагов, каждый из которых может упасть, и генерируют огромные логи. HTTP agent же позволяет сделать один запрос к серверу, получить большой JSON и извлечь из него десятки метрик: количество заказов, статус базы данных, версию API. Это снижает нагрузку на сеть и сам сервер, так как не нужно делать сотни отдельных запросов. Я помню случай, когда веб-сценарий грузил сервер так, что он падал под нагрузкой тестов. HTTP agent решает это элегантнее. Сервер Zabbix выполняет проверки асинхронно, поддерживая до 1000 одновременных проверок (параметр MaxConcurrentChecksPerPoller). Число поллеров задаётся параметром StartHTTPAgentPollers в конфигурации, а с версии 7.0 поддерживаются постоянные cURL-соединения, что ещё больше ускоряет работу. Это не просто «ещё один инструмент», это смена парадигмы: от проверки «жив ли сервер» к проверке «работает ли бизнес-логика».

Главное преимущество — возможность работать с сырыми данными, JSON и XML. Вы можете отправить тело запроса в формате Raw data, где макросы подставляются без кодирования, или использовать JSON data, где строковые макросы автоматически оборачиваются в кавычки, а значения экранируются. По умолчанию для JSON устанавливается Content-Type: application/json. Для XML нужен libxml2, и заголовок будет application/xml. Это позволяет взаимодействовать с любыми современными API без написания кастомных скриптов. Вы можете настроить Required status codes — список кодов, которые считаются успешными, например 200, 201 или диапазон 210-299. Если сервер вернёт код вне этого списка, элемент получит статус «неподдерживаемый», но помните: статус «Not Supported» также возникает при ошибке соединения или невалидном формате ответа. Это гораздо точнее, чем просто смотреть на статус 200. Веб-сценарии тоже умеют проверять статусы, но они не дают такой гибкости в обработке тела ответа без сложных регулярных выражений, которые часто ломаются при малейшем изменении формата HTML.

Схема работы HTTP agent с JSONPath и зависимыми элементами
Один запрос, множество метрик через предобработку.

Настройка HTTP agent: заголовки, авторизация и таймауты

При создании элемента типа HTTP agent в Zabbix 7.0 вы сразу сталкиваетесь с полем URL. Длина URL ограничена 2048 символами. Здесь нужно соблюдать одно правило безопасности: никогда не храните логины и пароли прямо в строке URL. Вместо этого используйте пользовательские макросы, например, {$USER} и {$PASS}. Zabbix поддерживает подстановку макросов не только в URL, но и в заголовках, и в теле запроса. Доступны стандартные макросы хоста: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, а также {ITEM.ID}, {ITEM.KEY} и пользовательские. Вы можете указать заголовки парами «атрибут: значение», и Zabbix корректно передаст их в запросе через cURL. Хранить пароли в открытом виде — это преступление против безопасности, которое рано или поздно приведет к компрометации. Используйте HTTP authentication: Basic, NTLM, Kerberos или Digest. Имя пользователя и пароль ограничены 255 символами и также поддерживают макросы. Это позволяет централизованно управлять учетными данными через глобальные макросы или LLD.

Уделите особое внимание настройке таймаута. Глобальный параметр Timeout в zabbix_server.conf по умолчанию равен 3 секундам, диапазон 1–30 секунд. Но для сложных API этого может быть мало. В элементе HTTP agent можно переопределить таймаут на уровне 1–600 секунд. Помните, что это время ограничивает и подключение, и сам запрос, поэтому одна проверка может занять до двух таймаутов (CURLOPT_TIMEOUT). Если вы не переопределили таймаут в элементе, он возьмется из глобальной конфигурации. Настройка таймаутов вслепую приведет к ложным тревогам, особенно если API работает медленно или сеть загружена. Также настройте Required status codes — список кодов, которые считаются успешными. Если сервер вернёт код вне этого списка, элемент станет неподдерживаемым. Для API это часто 200, 201 или диапазон 210-299. Не настраивайте таймауты вслепую, если не хотите видеть ложные тревоги. В кейсе «Грядка» мы увеличили таймаут до 15 секунд, так как 1С иногда требовала больше времени на обработку запроса, и стандартные 3 секунды вызывали ложные срабатывания.

Если вы используете прокси, убедитесь, что формат указан верно: [protocol://][username[:password]@]proxy.example.com[:port]. Без протокола Zabbix использует схему "http" по умолчанию, но это не гарантирует корректную работу с HTTPS-прокси. Порт по умолчанию для HTTP-прокси — 1080. При пустом поле можно задать переменные окружения http_proxy или HTTPS_PROXY для пользователя сервера Zabbix. Это удобно для корпоративных сетей, где весь трафик идет через шлюз. Прокси настраивается на уровне элемента, что дает гибкость в маршрутизации запросов к разным API.

Важно: Если вы используете прокси, убедитесь, что формат указан верно: [protocol://][user:pass@]proxy.example.com[:port]. Без протокола Zabbix использует схему "http". Порт по умолчанию для HTTP-прокси — 1080.

Магия JSONPath: извлекаем данные из ответа

Самая мощная функция HTTP agent — это предобработка через JSONPath. Представьте, что API возвращает огромный JSON с информацией о состоянии системы. Нам нужно только поле «status» или «count». Путь JSONPath начинается с символа доллара ($), обозначающего корень. Например, $.version.number извлечёт номер версии из объекта version. Если данные находятся глубоко вложенных структурах, используйте рекурсивный поиск через две точки .., как в $..id. Это вернёт все поля с именем id на любом уровне вложенности. Это не сложно, если знать синтаксис. JSONPath в Zabbix поддерживает сегменты: <name>, *, ['<name>'], ['<name>','<name>'], [<index>], [*], [<start>:<end>]. Конец диапазона исключается, отрицательные индексы считаются с конца. Можно использовать фильтры и операторы. Например, $.books[?(@.price < 10)].title вернёт названия книг дешевле 10 долларов. Поддерживаются математические операции (+, -, *, /) и логические (==, !=, <, >, &&, ||). Если вам нужно агрегировать данные, добавьте функции в конец пути: avg, min, max, sum, length, first. Например, $.orders[*].amount|sum посчитает общую сумму всех заказов.

Разница между определённым путём (definite) и неопределённым (indefinite) очевидна для тех, кто работал с данными. Определённый путь возвращает не более одного совпадения. Неопределённый путь (с использованием .., списков, срезов, фильтров) возвращает массив. Использование функции (avg, sum и т.д.) автоматически делает путь определённым, так как функция возвращает скалярное значение. Если вы используете путь без функции и он возвращает массив, Zabbix может не справиться с преобразованием в числовое значение для графика. Поэтому для метрик всегда используйте функции агрегации или выбирайте конкретный элемент массива. Например, $..id вернёт массив [1, 2, 3, 4], а $..id|first вернёт только 1. Это критично для настройки триггеров, которые ожидают конкретное значение, а не список. JSONPath позволяет фильтровать элементы по условию, например, $.books[?(@.category == "fiction" && @.price < 10)].title. Это мощный инструмент для извлечения именно тех данных, которые нужны бизнесу, без лишнего шума.

Также обратите внимание на суффикс ~, который возвращает имя свойства. Это полезно для динамического анализа структуры ответа. Если API меняет названия полей, вы можете использовать это для адаптации мониторинга. Но чаще всего нам нужны конкретные значения. Например, для Elasticsearch можно использовать URL localhost:9200/?pretty и предобработку JSONPath: $.version.number. Это даст точную версию кластера. Или для Nginx stub status можно использовать регулярное выражение в зависимом элементе: server accepts handled requests\s+([0-9]+) ([0-9]+) ([0-9]+). JSONPath не заменяет регулярные выражения, но для структурированных данных он намного надежнее и читаемее. Не пытайтесь парсить JSON регулярками — это путь к боли и ошибкам.

Сравнение мониторинга до и после внедрения HTTP agent
Отслеживаем бизнес-логику, а не только доступность.

Кейс «Грядка»: ловим ошибку в 1С, когда сайт работает

Рассмотрим реальную ситуацию с интернет-магазином товаров для сада «Грядка». У них 17 сотрудников, основной трафик идёт через сайт, а учёт ведётся в 1С. Проблема была следующей: сайт открыт, страницы грузятся быстро, но менеджеры не могли оформлять заказы. Оказалось, что API 1С возвращал код 200, но в теле JSON было сообщение об ошибке: «Блокировка базы данных». Обычный мониторинг не видел проблемы, так как статус был успешным. Мы настроили HTTP agent на проверку эндпоинта статуса 1С. Использовали JSONPath для извлечения поля "error_message". Если это поле не пустое, мы запускали триггер. Админы были в шоке, что система работала, а бизнес — нет. Мы не просто проверяли доступность, мы проверяли состояние бизнес-процесса. Это ключевой момент: мониторинг должен видеть бизнес, а не только пакеты.

Для оптимизации мы использовали зависимые элементы. Мастерский элемент делал один запрос к API и получал весь JSON. Затем три зависимых элемента извлекали из него: текущую версию сервиса, статус подключения к базе и текст ошибки. Это позволило избежать лишних запросов к перегруженной 1С. Триггер сработал мгновенно, когда появилось сообщение об ошибке, ещё до того, как первый клиент получил отказ. Мы также настроили проверку на отсутствие заказов за последний час, используя функцию count и историю значений, чтобы убедиться, что бизнес-процесс не остановился. Я всегда говорю: если вы не видите ошибку в JSON, значит, вы её просто не ищете. Лень — главный враг мониторинга. В этом кейсе таймаут в 3 секунды был недостаточным для обработки сложных запросов 1С. Увеличив его до 15 секунд, мы убрали ложные срабатывания при пиковых нагрузках. Это показывает, что настройки по умолчанию подходят не всем, и нужно адаптировать их под реальную инфраструктуру.

Особенно важно правильно настроить предобработку для проверки ошибок. Мы использовали шаг «Check for error in JSON». Этот шаг проверяет сообщение об ошибке уровня приложения по JSONPath. Если сообщение непустое — обработка останавливается с этой ошибкой, иначе продолжается. Это предотвращает запись некорректных данных в тренды. Если бы мы не использовали этот шаг, Zabbix мог бы сохранить пустую строку как значение, и триггер не сработал бы. А так, элемент стал неподдерживаемым, и мы получили алерт. Это критически важно для систем, где ошибка в теле ответа означает сбой, даже если HTTP-код 200. В «Грядке» это спасло от потери продаж в самый разгар сезона. Мы не ждали, пока клиенты начнут жаловаться, мы узнали о проблеме раньше.

В кейсе «Грядка» мы обнаружили, что таймаут в 3 секунды был недостаточным для обработки сложных запросов 1С. Увеличив его до 15 секунд, мы убрали ложные срабатывания при пиковых нагрузках.
Если у вас нет времени на тонкую настройку JSONPath или вы боитесь сломать мониторинг 1С, мы в «АйТи-Фреш» подготовим шаблон под вашу инфраструктуру за 2 дня. Цена такого внедрения — от 12 000 ₽ за до 50 ящиков мониторинга. Обсудить задачу

Зависимые элементы и предобработка: как не нагружать сервер

Один из главных плюсов HTTP agent в Zabbix 7.0 — возможность создания зависимых элементов. Мастерский элемент выполняет HTTP-запрос один раз, а зависимые элементы получают данные из этого ответа без повторных обращений к серверу. Это критически важно, когда вы мониторите множество параметров одного сервиса. Например, вы можете иметь один мастер, который получает JSON с метриками сайта, и 20 зависимых элементов, каждый из которых извлекает своё значение через JSONPath или регулярные выражения. Максимальное количество зависимых элементов на одного мастера — 29999, но помните про ограничение в 3 уровня вложенности зависимостей. Не нужно дублировать запросы ради одной цифры. У зависимого элемента нет собственного интервала опроса, он обновляется только когда обновляется мастер. Это снижает нагрузку на сеть и целевой сервер, что особенно важно для API с ограничениями по количеству запросов.

Предобработка данных — это мощный инструмент, который позволяет трансформировать полученные данные перед сохранением в базу Zabbix. После получения ответа можно применить регулярное выражение для извлечения нужной части, заменить символы, обрезать строку или даже выполнить JavaScript-скрипт. Например, если API возвращает время в миллисекундах, а вам нужны секунды, используйте Custom multiplier или JavaScript. В скрипт передаётся параметр value строкой; результат через return (приводится к строке); return null отбрасывает значение; ошибку вызывают throw. Также есть специальные шаги для проверки ошибок в JSON: если в ответе есть поле с ошибкой, сбор данных останавливается, и вы получаете уведомление. Это предотвращает запись некорректных данных в тренды. Чистота данных начинается здесь. Шаг «Check for error in JSON» проверяет сообщение об ошибке уровня приложения по JSONPath. Если сообщение непустое — обработка останавливается с этой ошибкой, иначе продолжается. Невалидный JSON ошибку не даёт, но это тоже важно учитывать.

Также стоит упомянуть шаг «Discard unchanged with heartbeat». Он позволяет отбрасывать значения, которые не изменились, с заданным периодом в секундах (минимум 1, суффиксы 30s/1m/2h/1d, макросы допустимы). Отброшенные значения не сохраняются и триггеры не вычисляются. Это полезно для экономии места в базе данных, когда данные меняются редко. Но будьте осторожны: если вы используете этот шаг, триггеры на основе этих данных могут не сработать, если значение не изменилось. Поэтому используйте его только там, где это действительно нужно. Шаг «Check for not supported value» всегда выполняется первым и ловит ошибки сбора до предобработки. Только одна операция change и только один вариант throttling (Discard unchanged) на элемент. Это ограничение важно помнить при настройке сложных цепочек предобработки.

Чек-лист важных настроек HTTP agent в Zabbix
Не упускайте эти шаги при настройке мониторинга API.

Триггеры на бизнес-логику: не только 200 OK

Создание триггеров на основе HTTP agent выходит далеко за рамки простого «сайт упал». Мы можем реагировать на изменения в бизнес-логике. Например, если количество новых заказов за последний час равно нулю, это тревожный сигнал, даже если сайт технически доступен. Для этого используется функция count с параметром времени. Синтаксис выражения: function(/host/key,parameter) оператор константа. Операторы eq (по умолчанию для чисел), ne, gt, ge, lt, le, like (по умолчанию для строк), bitand, regexp, iregexp. Оператор в двойных кавычках. Выражение count(/host/key,1h,"eq",0)>0 сработает, если за последний час не было ни одного значения, равного нулю (в зависимости от логики). Также можно использовать функцию nodata, чтобы обнаружить, что данные перестали приходить вообще, даже если сервер не упал. Мониторинг должен видеть бизнес, а не только пакеты.

Правильно настраивайте пороги срабатывания. Для числовых значений используйте операторы gt, lt, ge, le. Для строк — like, regexp, iregexp. Например, если поле status содержит слово "error«, триггер сработал: count(/host/key,5m,»like","error«)>0. Функция last() позволяет проверить последнее значение, а nodata() — отсутствие новых данных. Помните, что функции времени и nodata() пересчитываются каждые 30 секунд, поэтому минимальный период для таких проверок — 30 секунд. Это позволяет быстро реагировать на изменения, не создавая лишней нагрузки на систему. Я видел, как люди тратили часы на настройку триггеров, игнорируя базовые функции, и удивлялись, почему система не реагирует. Это не вина Zabbix, это ваша невнимательность. Документация приводит примеры: count(/host/icmpping,30m,,»0")>5; count(/host/key,10m,"like","error"); last(/host/web.test.fail[Scenario])<>0; last(/host/web.test.in[Scenario,,bps])<10000. Используйте эти паттерны, адаптируя их под свои задачи.

Также обратите внимание на ключи веб-сценариев, которые могут быть полезны для сравнения. Например, web.test.time[Scenario,Step,resp] возвращает время выполнения запроса. Обратите внимание на формат: ключ имеет форму web.test.time[Scenario,Step,resp], где Scenario, Step и resp — параметры в квадратных скобках. Это важно для правильного написания триггеров. История хранится 30 дней, тренды 90 дней. Для trapper-элементов можно использовать nodata(/example.example.com/tick,3m)=1. Режим "strict" делает функцию нечувствительной к доступности прокси. Но для HTTP agent чаще используются обычные функции. Главное — понимать, что триггер должен отражать реальную проблему бизнеса, а не техническую деталь. Если API возвращает 200, но данные некорректны, триггер должен сработать. Это и есть суть современного мониторинга.

Частые вопросы

Нужен ли агент Zabbix на сервере для HTTP agent?

Нет, HTTP agent работает на стороне сервера Zabbix или прокси. Агент на целевом сервере не требуется, достаточно открыть доступ к HTTP/HTTPS порту.

Можно ли использовать JSONPath для XML?

Нет, JSONPath работает только с JSON. Для XML в Zabbix есть отдельный шаг предобработки XML XPath.

Что делать, если ответ слишком большой?

Используйте зависимые элементы и извлекайте только нужные поля через JSONPath, чтобы не перегружать память и сеть полным ответом.

Как настроить авторизацию Basic в HTTP agent?

Выберите HTTP authentication: Basic и укажите логин и пароль в соответствующих полях, используя макросы для безопасности.

Можно ли проверить скорость ответа API?

Да, Zabbix автоматически собирает время выполнения запроса. Используйте ключ web.test.time[Scenario,Step,resp] или анализируйте метрики времени в зависимых элементах.

Столкнулись с похожей задачей? Обращайтесь — решим

Если у вас происходит что-то из описанного в этой статье — или любая другая проблема с ИТ-инфраструктурой, — обращайтесь в любое время. Мои специалисты и я лично разберём ситуацию, найдём настоящую причину и доведём до решения.

Возьмёмся и за разовую задачу, и за постоянное обслуживание. Первичная консультация — бесплатно и без обязательств.

📞 +7 903 729-62-41 ✈ Telegram @ITfresh_Boss

С уважением, Семёнов Евгений Сергеевич, директор «АйТи Фреш» — IT-аутсорсинг для компаний до 50 рабочих мест, 15+ лет практики

Источники

© ООО «АйТи-Фреш» · Москва · Все статьи
АйТи-Фреш (ООО «АЙТИ-ФРЕШ») · г. Москва, Щёлковское шоссе, д. 92, корп. 7 · +7 903 729-62-41 · info@itfresh.ru · Пн–Пт 9:00–19:00