Моніторинг 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), щоб сторінка перевірки не виглядала як помилка перевірки значення.