Skip to main content

Client Logging Strategy

Решение о стратегии фронтенд-логирования и его связи с серверной диагностикой.

Дата: 2026-02-22 Статус: Accepted Контекст: Предпродакшн-ревью системы observability

Проблема​

При диагностике проблем через Grafana (Loki) доступны только бэкенд-логи. Фронтенд-события (клики, навигация, состояние UI, ошибки API на стороне клиента) — слепая зона.

Вопрос: Нужно ли расширять клиентское логирование для полноценной диагностики?

Анализ​

Текущее покрытие​

СлойПокрытиеИнструмент
Backend HTTPПолноеRequest Logger Hook (auto)
Backend бизнес-логикаПолноеDomain tags [Quest], [Case], etc.
Backend бизнес-событияПолноеlogBusinessEvent() → [BUSINESS]
Backend отказыПолноеreason codes (NOT_COMPLETED, COOLDOWN, etc.)
Frontend lifecycleЧастичноеclientLogger — используется в bootstrapPerformanceTracker (summary, images)
Frontend user actionsНет—
Frontend API errorsНет (видны на backend)—
Frontend UI stateНет—

Типичные сценарии диагностики​

СценарийЧастотаДостаточно backend логов?
"Квест не засчитался"ЧастоДа — reason code в бэкенд логах
"Награда не пришла"ЧастоДа — [BUSINESS] event или warn с reason
"Ошибка 500"ИногдаДа — error в цепочке requestId
"Кнопка не работает"РедкоНет — но воспроизводится на staging
"Белый экран"РедкоЧастично — clientLogger покрывает загрузку
"Уникальный баг у одного пользователя"Очень редкоЗависит от случая

Рабочий процесс разработчика​

  1. Пользователь жалуется → /diagnostics по userId → 95% случаев root cause найден
  2. Не найден → разработчик воспроизводит на staging сам
  3. Проблема массовая (баг в коде), а не уникальная для одного пользователя
  4. Необходимость запрашивать действия у конечного пользователя — крайне редка

Решение​

Оставить clientLogger в текущем минимальном виде. Расширять по необходимости.

Что уже работает (оставляем)​

  • clientLogger для lifecycle (загрузка, phase transitions)
  • POST /api/client-logs endpoint (без авторизации, rate-limited)
  • Логи попадают в Loki как [ClientLog] → доступны в Grafana

Что НЕ делаем сейчас​

  • Расширение clientLogger на все user actions
  • Передача userId из frontend (требует рефакторинг auth flow)
  • Стандартизация frontend event categories
  • Отдельный скилл для добавления диагностических логов

Когда расширять​

Триггеры для пересмотра решения:

ТриггерДействие
>3 инцидентов за месяц, где бэкенд логов недостаточноДобавить userId в clientLogger
Повторяющийся класс проблем (e.g., "кнопка не работает")Добавить логирование API errors на фронте
Необходимость удалённой диагностики без stagingРасширить clientLogger до полной системы

Инфраструктура готова​

Когда понадобится расширение — всё уже на месте:

clientLogger.log() → POST /api/client-logs → backend stdout → Promtail → Loki → Grafana

Нужно только:

  1. Добавить userId в clientLogger после авторизации
  2. Расширить категории (те же domain tags что на бэке)
  3. Обновить /diagnostics для поиска [ClientLog]

Оценка: ~2-4 часа работы когда реально понадобится.

Альтернативы (отклонены)​

A. Полная фронтенд-система логирования​

Логировать все: API calls, navigation, clicks, state changes.

Отклонено: YAGNI. Бэкенд покрывает 95% диагностики. Дополнительная нагрузка на сеть и Loki без доказанной необходимости.

B. Скилл /instrument для динамического добавления логов​

Claude-скилл, который анализирует проблему и добавляет целевые логи в код.

Отклонено: Over-engineering. Claude уже умеет добавлять clientLogger.log() ad-hoc без формализованного скилла. Если потребуется — достаточно сказать "добавь фронтенд-логи для проблемы X".

C. Конвенция + Guidelines для фронтенд-логирования​

Документ аналогичный logging-guidelines.md, но для фронтенда.

Отклонено (пока): Преждевременно без реального использования. Создать вместе с расширением clientLogger, когда появится практика.

Последствия​

  • Разработчики продолжают использовать /diagnostics + ручное воспроизведение на staging
  • clientLogger остаётся для loading diagnostics — не трогаем
  • Решение пересматривается при появлении триггеров (см. таблицу выше)
  • Инфраструктура (endpoint, pipeline) уже готова для быстрого расширения