Перейти к основному содержимому

Looking Glass

Looking Glass предоставляет два независимых вида измерений:

  • Ручные Ping, Traceroute и MTR: из выбранной локации к вашему публичному IP-адресу или домену.
  • Задержка HTTPS: напрямую из браузера посетителя до локации. Это время обмена по HTTPS, а не ICMP ping.

Получение точек​

Вызывайте GET /looking-glass/points с вашего backend, передавая X-Api-Key и api_key_id. Применяется белый список IP интеграции. Необязательный location_id фильтрует список; при отсутствии совпадений возвращается пустой список.

Точка содержит ID, локацию, страну, город, публичные тестовые IP, ipv4_enabled, ipv6_enabled, доступные checks и три nullable URL задержки. Используйте ответ реестра, не фиксированный список локаций или адресов.

Отключённые точки остаются в списке. Наличие IP не означает разрешение диагностики. Назначение URL:

ПолеНазначение
latency_urlОсновной замер; при двух включённых семействах браузер выбирает семейство. При одном включённом возвращается его URL.
latency_ipv4_urlЗамер только по IPv4.
latency_ipv6_urlЗамер только по IPv6.

Отключённое семейство или ненастроенный hostname дают null. Отсутствие IPv6 у посетителя не означает недоступность локации по IPv4.

Ручная проверка​

Вызывайте POST /looking-glass/check только при запуске диагностики пользователем:

curl --request POST 'https://cloud-api.adaptgroup.pro/looking-glass/check' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--max-time 60 \
--data '{"api_key_id":1,"point_id":1,"type":"ping","family":4,"target":"1.1.1.1"}'

type — ping, traceroute или mtr; family — целое число 4 или 6. Цель — публичный числовой IP или домен без протокола, порта, пути и параметров. Числовой IP должен соответствовать выбранному семейству. DNS разрешается в выбранной локации. Внутренние и инфраструктурные адреса, включая домены, которые в них разрешаются, запрещены.

Вызов синхронный. Установите таймаут HTTP-клиента 60 секунд. Не повторяйте запрос автоматически после обрыва или HTTP 504: команда могла выполниться. Маршрут не использует Idempotency-Key.

Ответ содержит фактически проверенный IP в target, код команды return_code, timed_out, длительность выполнения duration_ms и output. Длительность выполнения — не задержка сети. Вывод Ping и Traceroute — текст, MTR — JSON-строка. Обрабатывайте ошибку разбора JSON и сохраняйте текстовый вариант отображения. Вывод вставляйте как текст, не HTML.

HTTP 200 может содержать ненулевой код команды или неполный результат: timed_out=true, return_code=null. Звёздочки в трассировке, неполученные ICMP-ответы и ненулевой код не доказывают недоступность всей локации.

Лимиты и ошибки​

Квоты ручных проверок независимы для каждой интеграции. Лимиты частоты используют скользящее окно 60 секунд; все ограничения действуют одновременно:

ОбластьПроверок в минутуОдновременно
API-интеграция, все точки3004
Интеграция + IP источника302
Интеграция + нормализованная цель60—
Интеграция + точка1202

Каждая региональная точка дополнительно ограничивает интеграцию до 120 проверок в минуту, а интеграцию + фактически разрешённый IP цели — до 60 в минуту. Разные домены, разрешающиеся в один IP, делят эту квоту цели. IPv6 источника группируется по /64 внутри интеграции. При запросах через ваш backend посетители делят лимит его IP по всем локациям внутри вашей интеграции. Другая интеграция с тем же IP имеет собственную квоту. Произвольные поля client_ip и api_id не принимаются.

Точка выполняет до четырёх проверок одновременно, не более двух от одной интеграции. При занятых слотах запрос ожидает до пяти секунд в очереди, которая обслуживает интеграции по раундам. От одной интеграции допускается не более двух ожидающих запросов на точку. Ожидание и отказ не расходуют квоту частоты; она списывается при допуске к выполнению. Мощность общая, поэтому квота не гарантирует 300 завершённых проверок в минуту. Заполненная очередь или истёкшее ожидание возвращают HTTP 429 с Retry-After: 60. Запрос остаётся синхронным и не возвращает ID задания; после завершения ожидающего запроса проверка из очереди не запускается в фоне.

HTTPКод / значение
401Неверная авторизация Cloud API.
403ip_not_allowed: IP источника не входит в белый список интеграции.
404lg_point_not_found: неизвестная точка.
409lg_point_disabled: точка или семейство отключены.
422Ошибка валидации запроса или lg_invalid_target: запрещённая цель либо ошибка DNS.
429lg_rate_limited: исчерпана личная квота, недоступна мощность точки, очередь заполнена или время ожидания истекло. Учитывайте Retry-After, сейчас 60 секунд.
502lg_agent_unavailable: точка недоступна или вернула некорректный результат.
503lg_unavailable: сервис недоступен; lg_client_ip_unavailable: не удалось определить IP источника.
504lg_timeout: результат диагностики не получен до истечения ожидания.

После 429 не запускайте цикл автоматических повторов. Разрешите новую проверку по действию пользователя после Retry-After. API не кеширует результаты диагностики и не хранит их историю.

Задержка HTTPS из браузера​

Ваш backend передаёт список точек на frontend. Браузер обращается к URL задержки напрямую, без API-ключа и cookies. Если проксировать запрос через backend, измерится его соединение вместо соединения посетителя.

  1. Один цикл при открытии страницы, не более трёх локаций одновременно. Пропускайте отключённые точки и null URL.
  2. Для каждой локации выполните один прогрев, затем пять последовательных замеров. Прогрев исключите: он может включать DNS/TCP/TLS.
  3. Таймаут каждого запроса — три секунды. Показывайте медиану при минимум трёх успешных замерах, иначе — «Замер недоступен».
  4. При HTTP 429 остановите замер точки и покажите «Повторите позже». Не повторяйте автоматически.
  5. По умолчанию измеряйте только latency_url. Отдельные IPv4/IPv6 URL используйте при выборе пользователя.
  6. При уходе со страницы отменяйте запросы через AbortController. Не запускайте цикл при каждом рендере или по фоновому интервалу. Результаты можно хранить в памяти вкладки 60 секунд; новый замер запускается отдельным действием.

У каждого запроса должен быть уникальный query-параметр и следующие настройки fetch:

const probeUrl = new URL(point.latency_url);
probeUrl.searchParams.set('probe', crypto.randomUUID());
const response = await fetch(probeUrl, {
credentials: 'omit',
cache: 'no-store',
mode: 'cors',
redirect: 'error',
signal: AbortSignal.any([pageAbortController.signal, AbortSignal.timeout(3000)]),
});
await response.arrayBuffer();

Endpoint возвращает пустой HTTP 200 с поддержкой CORS и Timing-Allow-Origin. Проверяйте статус; не используйте no-cors, скрывающий ошибки и ответы 429. При доступности Resource Timing используйте responseEnd - requestStart, иначе — разницу performance.now() вокруг fetch и чтения тела. Запасной вариант включает дополнительные накладные расходы браузера. Не очищайте общую таблицу Resource Timing страницы.

Добавьте https://*.lg.adaptgroup.pro в CSP connect-src вашего frontend. Подпишите результат «Задержка HTTPS». HTTP-таймауты не являются процентом потерь ICMP и не доказывают падение локации.

Эти запросы не расходуют квоту ручных проверок. Отдельные лимиты каждой точки: 20 запросов/с на IP с burst 40, 500/с на точку с burst 100, 8 одновременных запросов на IP и 128 на точку. Посетители за одним NAT делят его лимиты.

© 2026 AdaptGroup LLC. All rights reserved.
30 N Gould St Ste R, Sheridan, WY 82801, USA
Back to top