Мониторинг API с проверкой значений в JSON и телом запроса

Начните с эндпоинта, который не врёт

Самый полезный монитор API — это не вызов самого загруженного эндпоинта, а вызов служебного маршрута, который проверяет важное. Поверхностный маршрут, возвращающий {"ok":true}, доказывает только то, что процесс запущен. Маршрут, который обращается к базе данных и очереди и сообщает о каждой отдельно, даёт вам, что проверять:

{"status":"ok","database":"ok","queue":"ok","version":"4.12.1"}. В мониторе типа JSON API вы указываете одно значение этого документа, например database, и то, каким оно должно быть. Когда соединение с базой обрывается, маршрут всё равно отвечает 200, но JSON уже не совпадает, и в инциденте видно, какое именно значение не то. Пусть маршрут будет дешёвым и без аутентификации или защищённым только секретным заголовком, чтобы мониторинг не стал источником нагрузки.

Как проверяется значение

Тело ответа разбирается как JSON; если не получается, проверка завершается ошибкой «Response is not valid JSON». Затем вычисляется ваш путь: точки заходят в объекты, число или [0] выбирает элемент массива, а необязательный начальный $ принимается, так что status.database, $.status.database и items[0].id — всё допустимые записи. Отсутствующий путь даёт ошибку «JSON path not found». Если вы задали ещё и ожидаемое значение, фактическое должно ему равняться. Строки сравниваются без учёта регистра, числа и булевы значения — по текстовой записи (true, 42), а объекты и массивы — как JSON.

Это намеренно только равенство. Операторов «меньше» или «содержит» пока нет. Если нужен порог, пусть API сам вычислит вердикт и отдаст его значением: queue_ok:true проверять проще, чем queue_depth<100. Если указать путь без ожидаемого значения, проверка просто потребует, чтобы путь существовал.

Методы, тела запросов и учётные данные

Можно использовать GET, HEAD, POST, PUT, PATCH и DELETE. Тело запроса отправляется для всех методов, кроме GET и HEAD, а если оно начинается с { или [ и тип содержимого вы не задали, уйдёт как application/json. Аутентификация бывает двух уровней. Basic auth — это поле в расширенных настройках на всех тарифах. Bearer-токены и API-ключи в заголовках требуют тарифа Pro, потому что собственные заголовки — функция Pro: редактор так и говорит, а не отбрасывает их молча.

Осторожно с методами, которые меняют данные. POST каждую минуту — это 1440 записей в сутки, а монитору, который создаёт запись, нужен план очистки. Отдавайте предпочтение идемпотентным чтениям, отдельному токену только для чтения или эндпоинту, созданному для таких проверок. Никогда не направляйте монитор с DELETE на рабочие данные.

Когда «неправильный» статус ожидаем намеренно

Поле ожидаемого статуса — это проверка контракта не меньше, чем проверка доступности. Вызов защищённого эндпоинта без токена с ожиданием 401 доказывает, что слой аутентификации жив и не пускает всех подряд. Ожидание 404 на пути, который должен оставаться скрытым, — дешёвый регрессионный тест на изменение маршрутизации. Для публичного API с ограничением частоты значение 200,429 не даёт оповещению об ограниченном ответе вас разбудить, но сбои 500 и 502 всё равно ловит. Диапазоны и отдельные коды в одном списке можно сочетать.

Задержка и порог медленного ответа

Каждый вызов сохраняет время ответа. На Pro и Agency задайте порог медленного ответа в миллисекундах, и Tenium будет сравнивать его со средним трёх последних проверок, открывая при превышении инцидент об ухудшении, а не о недоступности. Усреднение трёх значений не даёт реагировать на один холодный старт, но при интервале в одну минуту регрессию видно уже через несколько минут. Поскольку среднее берётся по проверкам, которые могут идти из разных регионов, в пороге стоит учесть дополнительное расстояние до самого дальнего проверяющего сервера.

Ограничения, о которых стоит знать

Каждый монитор — это один запрос. Цепочек (сначала вход, потом вызов с токеном), проверки схемы ответа и проверки заголовков нет. Тело читается примерно до 1 МБ без сжатия, поэтому очень большой эндпоинт со списком — плохой выбор для монитора. Проверка JSON начинается с тарифа Starter за $7 в месяц; на Free тот же адрес можно отслеживать как обычный монитор сайта по статусу и скорости. Если ваш API стоит за WAF, добавьте адреса проверяющих серверов в белый список (allow-list), чтобы страница проверки не выглядела как ошибка проверки значения.