Инструмент мониторинга API: аптайм, время отклика и валидация из 300+ локаций

Мониторинг REST API внешне похож на мониторинг аптайма, но по сути это другая задача. API потребляется кодом, а не людьми, и код беспощаден там, где браузер снисходителен. Реальный посетитель мирится со страницей, которая отрисовалась чуть неправильно; интеграция, получившая поле неверного типа, просто ломается. Поэтому мониторинг API должен проверять больше уровней, чем «ответил ли сервер», и HostTracker проверяет их по порядку, останавливаясь на первом же уровне, который не выдержал.

Уровни один-три - это то, что даёт обычная проверка аптайма. Четыре и пять - это то, что делает проверку именно мониторингом API, и именно на этих уровнях живёт большинство реальных инцидентов API.

Прежде чем что-либо можно будет проверить, монитору нужно выполнить именно тот запрос, который ожидает ваш API. На API-мониторе доступна полная поверхность запроса:

Самый выразительный способ проверить ответ - написать для него правила. Каждое правило - это одна строка, правила объединяются через И, и монитор может нести до двадцати таких правил. Вот проверенный стартовый набор для JSON API:

status isOk
header("Content-Type") contains "json"
body.json.path("$.count") gt 0
time lt 5s

Четыре строки, и вместе они покрывают четыре важных уровня: эндпоинт ответил кодом 2xx, ответил именно JSON, а не страницей ошибки, payload содержит реальный результат, а не пустой, и всё это уложилось в бюджет времени. Другие полезные по отдельности правила из того же каталога включают body.json.path("$.status") eq "ok" для собственного вердикта здоровья API, body.json.path("$.error") absent для поля ошибки, появившегося в остальном успешном ответе, body.json.path("$.version") eq "2.4.1", чтобы поймать непреднамеренный откат версии, redirects.count eq 0 для эндпоинта, который должен отвечать напрямую, и cert.days.left gt 14 для сертификата на том же соединении.

О чём может говорить правило

Правила читают субъекты из ответа и сравнивают их. Субъекты покрывают код состояния; общее время ответа и его составляющие - подключение, TLS, DNS, заголовки и тело; сырое тело вместе с его размером и его хешем; структурированные запросы к payload как к JSON, XML, HTML или YAML; отдельные заголовки ответа; итоговый и исходный URL и их части; цепочку редиректов, переход за переходом; оставшиеся дни сертификата, издателя и имена; согласованные протокол TLS и шифр; адреса, которые вернул DNS; и Set-Cookie. Сравнения работают от очевидных - равно, меньше чем, больше чем - до contains, startsWith, endsWith, matches для регулярного выражения, containsAny и containsAll для набора, in для списка допустимых значений, а также exists, isNumber и unique.

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

Наряду с языком правил есть более простой путь для одного значения, который давно является частью мониторинга API и которого часто вполне достаточно для проверки. Вы указываете монитору, как разобрать тело, как выбрать из него одно значение и каким это значение должно быть:

• Разобрать как JSON, и селектор - это выражение JSONPath.
• Разобрать как XML, и селектор - это выражение XPath, что делает простой проверку SOAP и других XML-сервисов.
• Трактовать как обычный текст, и селектор - это многострочное, нечувствительное к регистру регулярное выражение.

Предикат, применяемый к выбранному значению, покрывает равно и не равно, меньше и больше в строгой и включительной форме, принадлежность списку допустимых значений или исключение из него, попадание в числовой диапазон или вне его, и проверку того, является ли значение null или отсутствует вовсе.

Каждый сбой в этой таблице возвращает HTTP 200. В этом вся проблема мониторинга API только по коду состояния: транспорт отработал успешно, поэтому транспорт и сообщает об успехе.

Последнюю строку стоит сделать намеренно. Второй монитор, который не отправляет учётные данные и проверяет код 401, - это самый дешёвый способ узнать, что уровень авторизации случайно отключили, - сбой, который никакое количество позитивного тестирования никогда не выявит.

API-мониторы работают с публичного флота чекпоинтов HostTracker - более 300 чекпоинтов в 158 городах, - и вы сами выбираете, какие локации использует конкретный монитор. География важнее для API, чем для сайта: эндпоинт за CDN или геораспределённым балансировщиком нагрузки может быть здоров во Франкфурте и неисправен в Сан-Паулу, а проверка из одной локации никак этого не увидит. То же касается и DNS - устаревшая или неправильно настроенная запись часто распространяется неравномерно, что изнутри выглядит как периодический сбой, а снаружи - как региональный.

Проверка из множества мест несёт очевидный риск: чем больше чекпоинтов, тем больше шансов, что один нестабильный сетевой путь поднимет ложную тревогу. HostTracker решает это кворумом подтверждения. Когда чекпоинт сообщает о сбое, проверка повторяется на дополнительных независимых чекпоинтах, и изменение состояния подтверждается только после того, как они сойдутся во мнении - по умолчанию это вердикт большинства среди до семи агентов, минимум трёх. Вы можете сделать это строже, потребовав определённое число агентов, сообщивших о сбое, или полного согласия между ними - для эндпоинта, где ложная тревога хуже, чем медленная.

После подтверждения оповещение следует задержке, которую выбрал каждый контакт - немедленно, либо через 3, 5, 15, 30 или 60 минут, либо через 3, 6, 12 или 24 часа непрерывного сбоя, - по девяти каналам уведомлений: email, SMS, голосовой звонок, webhook, Slack и мессенджеры Telegram, Discord, Viber, Facebook Messenger и Google Chat. Канал webhook - это способ доставить оповещение в систему управления инцидентами или в командный чат.

Проверка - это настраиваемый HTTP-запрос плюс анализ ответа, поэтому то, что она умеет проверять, следует прямо из этого.

• REST и JSON API - повседневный случай, и мониторинг REST API - это то, что настраивает первым большинство аккаунтов: GET или POST, заголовки для учётных данных, JSONPath или правила проверки по payload.
• GraphQL работает как POST с запросом в теле, а затем JSONPath внутрь data - и стоит проверить, что поле errors отсутствует, поскольку GraphQL славится тем, что отвечает 200 с ошибками внутри.
• SOAP и XML-сервисы - это POST с конвертом в качестве тела и XPath в роли селектора, что позволяет добраться до ответа именно так, как и задумано спецификацией.
• Приёмники вебхуков и конечные точки обратного вызова можно проверять на доступность и на ответ, который они дают на корректно сформированный запрос, - это ценно, потому что приёмник, который незаметно перестал принимать доставки, не вызывает ошибку нигде в вашей собственной системе.
• Эндпоинты health и readiness - самая ценная цель из всех, если они у вас есть: ваше приложение уже знает, здоровы ли его зависимости, и утверждение по этому вердикту превращает собственное знание приложения в оповещение.

Что не подходит - это последовательность: получить токен, использовать его, затем удалить ресурс. API-монитор делает один запрос за запуск. Для настоящего многошагового сценария нужен браузерный монитор транзакций; для тайминга страницы, а не эндпоинта, см. мониторинг тайминга доступа в браузере.

1. Сначала опробуйте эндпоинт с помощью бесплатной мгновенной HTTP-проверки - вход не требуется, - чтобы увидеть статус, тайминг и ответ, для которого вы собираетесь писать правила.
2. Добавьте монитор и выберите тип «Мониторинг API». Задайте метод, добавьте заголовки или тело, которые требует эндпоинт; выпустите монитору собственные учётные данные, а не переиспользуйте чужие.
3. Напишите правила проверки. Начните с четырёхстрочного набора выше - статус, тип содержимого, одно значимое значение из payload и бюджет времени ответа, - который на практике является хорошим значением по умолчанию почти для любого JSON API.
4. Выберите интервал от одной минуты до 24 часов. Три минуты - значение по умолчанию и разумная стартовая точка; одну минуту оставьте для эндпоинтов, сбой которых является инцидентом.
5. Выберите локации. Два-три региона, где реально находятся ваши потребители, лучше одного, и именно это делает региональный сбой заметным.
6. Добавьте контакты и задайте задержку оповещения для каждого. Не всем нужно узнавать об этом на первой минуте.
7. Дайте монитору поработать день, а затем посмотрите историю времени ответа, прежде чем ужесточать правило по таймингу. Бюджет, заданный на основе реальных данных, держится; заданный наугад заглушается.

Это взаимодополняющие инструменты, которые часто путают. Платформа наблюдаемости или APM инструментирует ваш код и сообщает, что происходило внутри запроса. Внешний мониторинг API стоит вне вашей инфраструктуры и сообщает, что реально получает потребитель. Оба стоит иметь; ни один не заменяет другой.

Схема, к которой в итоге приходит большинство команд, - внешний мониторинг для обнаружения и внутренняя телеметрия для диагностики: HostTracker сообщает вам, что эндпоинт сломался, откуда и по какому правилу, а ваш собственный трейсинг объясняет, почему. Вместе с этим монитор запросов к базе данных часто объясняет, почему API стал медленным, а мониторинг нагрузки сервера объясняет состояние хоста, на котором он работает.

• Один запрос за запуск. Никакого обмена токеном, никаких цепочек вызовов. Направьте монитор на эндпоинт, чья аутентификация не истекает, а для сценария, где нужно доказать именно последовательность, используйте монитор транзакций.
• Двадцать правил проверки на монитор. На практике этого более чем достаточно - четырёхстрочный набор покрывает большинство эндпоинтов, - но об этом стоит знать, прежде чем планировать контрактный тест на сотню правил.
• Режим проверок-утверждений заменяет старые настройки ключевых слов и статуса. Две модели нельзя совмещать на одном мониторе; выбирайте либо язык правил, либо старый режим ключевых слов, но не оба сразу.
• Нет валидации по OpenAPI или JSON-схеме. Вы проверяете конкретные значения и структуры, а не всю схему целиком.
• У тела запроса есть ограничение длины, так что очень большой POST-payload - не та форма, под которую построена эта проверка.
• Это мониторинг, а не тестирование. Правильная цель - эндпоинт только для чтения или идемпотентный. Монитор, изменяющий данные каждые три минуты из нескольких локаций, рано или поздно станет причиной инцидента, а не тем, что его обнаруживает.