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

2026-09-23 — Клиентские ошибки: видимость во фронтовых сбоях

Статус: Реализовано (на stage: бек #756, фронт #789)

Источник / заказчик: Олег

Эпик: ITR-3097

Задачи: RequestId — ITR-3099; приём и фронт — ITR-3100.

Документ — договорённость для технической работы. Памятка «как искать в логах»: integrations.md (§ Логи и объектное хранилище). Пользовательский changelog: пункт в versions.json (v1.14.0) — «Ошибки интерфейса дополнительно фиксируются в системных логах…».

Цель​

Сделать так, чтобы при сбое на стороне браузера (toast «не удалось», обрыв сети, ошибка после успешного ответа API) можно было найти след в тех же логах, куда уже пишет бек (Serilog → файлы / S3), и связать его с конкретным HTTP-запросом.

Не цель — писать с фронта напрямую в S3 и не цель — дублировать с клиента ответы API с кодами 4xx и 500, которые бек уже фиксирует в своих логах.

Контекст​

Как было​

  • Логи приложения писал только бек; фронтовые сбои уходили в console / toast.
  • Типичный инцидент: UI «чат не создался», в БД и серверных логах — успех.
  • В шаблонах Serilog был RequestId, но клиенту он не отдавался.

Как стало​

  • HTTP-ответы API отдают X-Request-Id (middleware); тот же id — в Serilog как RequestId.
  • Авторизованный фронт шлёт отчёты о сбоях (кроме HTTP 4xx и 500); бек пишет строку с префиксом UX error:.
  • Прямой записи из браузера в Object Storage нет.

Сценарии разбора (для разработки / поддержки)​

  1. Расхождение UI и бека. В логах найти UX error:, взять FrontendRequestId (id исходного API-запроса) → искать тот же id как RequestId у бизнес-запроса.
  2. Сеть / таймаут / ошибка без HTTP-статуса. В отчёте — детали; FrontendRequestId, если ответ успели получить.
  3. Error Boundary / unhandled rejection / window error. Отчёт без обязательной привязки к HTTP.
  4. HTTP 4xx или 500. Смотреть серверные логи запроса; клиентский UX error: по ним не ждать.

Принятые решения (итог реализации)​

ТемаРешение
Куда писатьБек → Serilog (файлы / S3). Не с фронта в S3
Фильтр в логахПрефикс текста UX error: (отдельное свойство «источник = Client» не заводили)
Авторизация / праваЛюбой авторизованный; identity из токена
До логинаПубличный приём не делали
RequestIdMiddleware: заголовок X-Request-Id, свойство RequestId в Serilog; входящий id с санитизацией; CORS exposed
Корреляция UX ↔ APIВ записи UX error: свойство FrontendRequestId = X-Request-Id исходного запроса. У самого POST отчёта свой (другой) RequestId — это id приёма отчёта
Что шлёт фронтAxios interceptor (все вызовы через общий HTTP-клиент); Error Boundary; window.error / unhandledrejection. Не шлёт при HTTP 4xx и 500
Защита приёмаЛимит тела ~10 КБ; rate limit (конфиг, ориентир 50/мин на IP); отправка через fetch без редиректа на 401
Sentry и т.п.Не в эпике

Правило отправки с фронта​

ошибка сети / unhandled / Error Boundary
→ HTTP status 4xx или ровно 500? → не слать
→ иначе (нет статуса, 502/503, …) → слать

Критерии приёмки​

  • HTTP-ответы отдают X-Request-Id; тот же id в серверных логах; CORS exposed.
  • Авторизованный фронт шлёт отчёт; в Serilog строка UX error: ….
  • Неавторизованный вызов отклоняется.
  • Лимит размера и rate limit.
  • Не дублируются с клиента HTTP 4xx и 500.
  • Сбой отправки отчёта не ломает UX и не зацикливает логин.
  • Прямой записи логов из браузера в S3 нет.
  • По FrontendRequestId / X-Request-Id можно найти исходный серверный запрос.
  • Памятка: искать UX error:, связь по id — в integrations.md.

Вне scope​

  • Прямая запись фронта в Object Storage.
  • Публичный приём с /login.
  • Sentry / session replay.
  • Enricher Serilog «источник = Client».
  • Размазывание RequestId по контроллерам (путь — middleware).
  • Переработка toast ради логирования.
  • Web Vitals / продуктовая аналитика.

Задачи эпика​

#ЗадачаСмыслСтатус
1Задача 1. Бек. RequestId в заголовках (middleware)ITR-3099Сделано
2Задача 2. Бек. Приём клиентских ошибокITR-3100Сделано
3Задача 3. Фронт. Сбор и отправка клиентских ошибокITR-3100Сделано
4Задача 4. Документация. Как искать UX error в логахПамятка в integrations + фиксация итога здесьСделано