Запросы из браузера и трасса бэкенда

Ошибка в браузере часто — только следствие: сервер ответил 500, и интерфейс упал, не получив данных. NablOps связывает две стороны. На вкладке «Запросы» фронтенда видно, какие обращения к вашему API делает приложение из браузеров посетителей, как часто они падают и сколько ждёт человек. А из ошибки фронтенда, случившейся после упавшего запроса, ссылка «трасса запроса» открывает трассу этого запроса на сервере — где именно он сломался и какие запросы к базе успел сделать.

Нужен @nablops/react 0.4.0 и новее (NablOps 0.31.0). Запросы пакет видит сам, отдельно включать ничего не нужно.

Что пакет видит в запросах из браузера

Пакет перехватывает fetch и XMLHttpRequest и для каждого запроса запоминает метод, адрес, статус ответа и время ожидания.

  • Неудачные запросы уходят все: ответы 5xx, 4xx и запросы без ответа (сеть, CORS, обрыв, блокировщик).
  • Успешные — выборкой, по умолчанию 10 %. Число на вкладке пересчитано с учётом выборки, поэтому оно близко к настоящему.
  • Адрес — без query и fragment, числа и UUID в пути заменяются на :id: /api/orders/1042 превращается в /api/orders/:id. Запросы на чужой домен показываются вместе с хостом.
  • Тела запросов и ответов пакет не читает.

Запросы к самому NablOps пакет не перехватывает.

Вкладка «Запросы»

На вкладке «Запросы» фронтенда — обращения к API за сутки или 7 дней, сгруппированные по методу и адресу:

Колонка Что показывает
«Запрос» метод и адрес, например GET /api/orders/:id
«Число» сколько было запросов (с пересчётом выборки)
«Ошибки» доля ошибок сервера и сбоев сети, отдельно — сколько ответов 4xx
«p75 / p95» время ожидания глазами посетителя: 75-й и 95-й перцентиль, мс
«Статусы» частые коды ответа; «сеть» — запрос не получил ответа

В последней колонке у запроса, который падал, — ссылка «последний сбой»: она открывает трассу последнего упавшего запроса на бэкенде. Запросы хранятся 14 дней.

Время в «p75 / p95» — то, что видит посетитель: оно включает сеть и очередь браузера. Если на бэкенде запрос быстрый, а в браузере медленный, причину стоит искать между ними — в сети, прокси или размере ответа.

Запросы в хронологии сессии

На странице сессии запросы стоят в «Хронологии» между переходами, кликами и ошибками: метод, адрес, статус и ссылка «трасса», если бэкенд продолжил трассу. Так видно, какой запрос упал прямо перед ошибкой и что человек делал до этого.

Как из ошибки фронтенда перейти в трассу бэкенда

Если ошибка в браузере случилась не позже 10 секунд после запроса, который получил 5xx или не получил ответа, пакет связывает их. На странице ошибки у такого повтора появляется ссылка «трасса запроса». Она ищет трассу в стеках проекта и открывает её на вкладке «Трассировка» нужного стека: какой сервис принял запрос, где он упал, какие запросы к базе и другим сервисам успел сделать.

Как это работает: пакет добавляет к запросам заголовки traceparent и baggage (стандарт W3C Trace Context). Бэкенд с OpenTelemetry продолжает трассу с тем же идентификатором, и NablOps находит её по нему. В baggage уходят только id сессии и id пользователя из nabl.setUser — без email и имени.

Если трасса не нашлась, кабинет объяснит почему: бэкенд не продолжает трассу (нет OpenTelemetry или заголовок не дошёл из-за CORS), запрос не дошёл до бэкенда или трасса старше срока хранения.

Что нужно, чтобы ссылка на трассу работала

Бэкенд с трассировкой в том же проекте

Бэкенд должен продолжать трассу: OpenTelemetry SDK с пропагатором W3C TraceContext (он стоит по умолчанию) и отправкой трасс агенту стека в этом же проекте. Как подключить — в статье трассировка OpenTelemetry. Без этого запросы и их статусы на вкладке «Запросы» видны, но ссылка на трассу ничего не найдёт.

Трассы хранятся 7 дней, трассы с ошибками — 30.

API на том же домене

Если приложение и API работают на одном домене (https://app.example.com и https://app.example.com/api/…), настраивать ничего не нужно: по умолчанию заголовки добавляются только к запросам на свой домен.

API на другом домене: tracePropagationTargets и CORS

Если API на другом домене (https://api.example.com у приложения на https://app.example.com), нужны две вещи.

1. Перечислите адрес API в init:

ts
nabl.init({
  key: 'pk_…',
  endpoint: 'https://app.nablops.io/nabl',
  tracePropagationTargets: ['https://api.example.com', '/api/'],
});

Строка совпадает, если она входит в адрес запроса; для своего домена строка, начинающаяся с /, сравнивается с началом пути. Для шаблона адресов подойдёт RegExp. Когда список задан, он заменяет правило «только свой домен», поэтому если часть API живёт и на своём домене, добавьте и её путь, как /api/ в примере.

2. Разрешите заголовки в CORS бэкенда:

text
Access-Control-Allow-Headers: traceparent, baggage

Добавьте их к уже разрешённым заголовкам. Сначала настройте CORS, потом tracePropagationTargets: иначе браузер отклонит запрос с новыми заголовками ещё на preflight, и запрос упадёт у всех посетителей.

Сторонним API — платёжкам, картам, аналитике — заголовки не уходят, пока вы сами не добавите их адреса в список, поэтому их CORS не сломается.

Настройка выборки и отключение

ts
nabl.init({
  key: 'pk_…',
  sampleRate: { errors: 1, requests: 0.1 }, // доля ошибок и успешных запросов
  // captureRequests: false,                // не следить за запросами совсем
});

sampleRate.requests меняет долю успешных запросов, которые попадают в NablOps; неудачные уходят всегда. captureRequests: false выключает перехват запросов — тогда пропадут и вкладка «Запросы», и ссылки на трассу.

Что видит ИИ-ассистент

ИИ-ассистент видит то же, что и вы: запросы фронтенда с долей ошибок и временем ответа, запросы в хронологии сессии и связь ошибки браузера с трассой бэкенда. Поэтому он сам проходит путь от ошибки у посетителя до причины на сервере: открывает ошибку фронтенда, находит связанную трассу, смотрит, какой сервис и какой запрос к базе упал, и по ошибкам приложения находит исключение на бэкенде. Если трасса не находится, ассистент подскажет, чего не хватает — OpenTelemetry на бэкенде или CORS-заголовков.

Что дальше

Попробуйте NablOps

Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.

Создать аккаунт

Нашли неточность или не хватает ответа? Напишите в поддержку