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 нет.
Сценарии разбора (для разработки / поддержки)
- Расхождение UI и бека. В логах найти
UX error:, взятьFrontendRequestId(id исходного API-запроса) → искать тот же id какRequestIdу бизнес-запроса. - Сеть / таймаут / ошибка без HTTP-статуса. В отчёте — детали;
FrontendRequestId, если ответ успели получить. - Error Boundary / unhandled rejection / window error. Отчёт без обязательной привязки к HTTP.
- HTTP 4xx или 500. Смотреть серверные логи запроса; клиентский
UX error:по ним не ждать.
Принятые решения (итог реализации)
| Тема | Решение |
|---|---|
| Куда писать | Бек → Serilog (файлы / S3). Не с фронта в S3 |
| Фильтр в логах | Префикс текста UX error: (отдельное свойство «источник = Client» не заводили) |
| Авторизация / права | Любой авторизованный; identity из токена |
| До логина | Публичный приём не делали |
| RequestId | Middleware: заголовок 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 + фиксация итога здесь | Сделано |