Журналы и диагностика¶

Что вы сделаете¶

Вы научитесь получать ровно тот фрагмент журнала, который нужен для диагностики, не выгружая гигабайты текста и не раскрывая пароли, ключи или содержимое пользовательских документов.

1. Журнал — не ответ, а доказательство¶

Лог полезен только вместе с контекстом:

время
+
действие пользователя
+
компонент
+
код ошибки
+
идентификатор запроса

Сообщение 403 без понимания сервиса и ресурса почти бесполезно.

2. Базовая команда¶

Для контейнерного компонента:

docker compose logs --tail=200 <service>

Для наблюдения в реальном времени:

docker compose logs -f <service>

Останавливайте просмотр Ctrl+C после воспроизведения проблемы.

3. Не начинайте с «всех логов»¶

Плохо:

docker compose logs > everything.txt

и отправить файл кому-либо без просмотра.

Лучше:

определить симптом;
определить компонент;
воспроизвести;
взять 100–300 строк вокруг события;
удалить секреты;
приложить время и шаги.

4. Какой журнал смотреть¶

Проблема входа¶

Смотрите:

api;
компонент корпоративного входа, если используется;
proxy.

Ошибка разговора¶

Смотрите:

api;
model-manager;
model-runtime;
redis при проблемах потокового состояния.

Файлы/RAG¶

Смотрите:

api;
rag-api;
vectordb.

Интернет-поиск¶

Смотрите:

web-search;
web-scraper.

Яндекс Облако¶

Смотрите:

yandex-gateway;
FinOps-компонент для Billing.

5. Ошибка API¶

Ищите:

код HTTP;
путь;
время;
идентификатор пользователя без раскрытия лишних персональных данных;
идентификатор запроса;
текст исключения.

Не публикуйте полный заголовок Authorization.

6. Ошибка модели¶

Ищите:

идентификатор модели;
этап install/start/ready;
CUDA/OOM;
свободную память;
ошибку загрузки артефакта;
ошибку лицензии/совместимости;
последний сбой активации.

Параллельно снимите:

nvidia-smi

7. Ошибка поиска по документам¶

Нужно понять этап.

В журнале ищите:

upload
parse
embedding
index
query
retrieval

Буквальные названия событий могут отличаться, поэтому привязывайтесь к времени тестового файла.

8. Ошибка Яндекс Облака¶

Не копируйте весь запрос с секретами.

Полезно сохранить:

HTTP-код;
сервис;
Folder ID в обезличенном виде при необходимости;
request-id;
тип операции;
роль служебной учётной записи;
результат yc-doctor без секретов.

9. Request ID¶

Если внешний сервис возвращает идентификатор запроса, сохраняйте его.

Это значительно полезнее, чем огромный снимок экрана.

Пример записи в заявке:

Время: 2026-09-15 10:42:13 MSK
Сервис: Yandex AI
HTTP: 403
Request ID: <идентификатор>
Действие: probe модели

10. Что считать секретом¶

Перед передачей журнала удалите:

пароль;
API-ключ;
закрытый ключ;
IAM-токен;
cookie сеанса;
заголовок авторизации;
строку БД с паролем;
содержимое .env;
временный код входа;
приватный URL с подписью;
содержимое конфиденциального документа, если оно не нужно для диагностики.

11. Простая маскировка¶

Не заменяйте секрет на похожий «почти настоящий» секрет.

Пишите явно:

Authorization: [СКРЫТО]
API_KEY=[СКРЫТО]
password=[СКРЫТО]

Так поддержка понимает, что значение существовало, но было удалено.

12. Персональные данные¶

Логи могут содержать:

адрес электронной почты;
имя пользователя;
имя файла;
поисковый запрос;
часть сообщения.

Перед передачей третьей стороне применяйте политику минимизации данных организации.

13. Время¶

Всегда указывайте часовой пояс.

Плохо:

сломалось около 10

Хорошо:

2026-09-15 10:14:22 MSK

или используйте ISO-формат с смещением.

Контейнер может писать UTC, а браузер — локальное время пользователя.

14. Перезапуск стирает контекст¶

Перед перезапуском проблемного компонента:

сохраните текущий журнал;
зафиксируйте docker compose ps;
зафиксируйте ресурсы хоста;
только затем перезапускайте.

Иначе вы можете потерять самое полезное состояние проблемы.

15. Диагностика циклического перезапуска¶

docker compose ps

Затем:

docker compose logs --tail=300 <service>

Проверьте:

права файлов;
конфигурацию;
недоступную зависимость;
нехватку памяти;
занятый порт;
ошибку миграции;
недоступный секрет.

16. Поиск по журналу¶

Для больших логов используйте фильтрацию:

docker compose logs --since=30m <service>

или:

docker compose logs --since=30m <service> | grep -Ei 'error|warn|fail|403|401'

Не используйте grep error как единственный критерий: некоторые ожидаемые отрицательные тесты также создают ошибки.

17. Диагностическая заявка¶

Хорошая заявка содержит:

Версия Студии:
Время:
Роль пользователя:
Компонент:
Ожидалось:
Фактически:
Шаги воспроизведения:
HTTP-код:
Request ID:
Фрагмент журнала:
Что уже проверено:

18. Что не надо делать¶

Не отправляйте в поддержку:

cat .env

или:

docker inspect ...

целиком без очистки: такие данные могут содержать секреты и переменные окружения.

19. Хранение журналов¶

Определите:

срок хранения;
максимальный объём;
ротацию;
кто имеет доступ;
входят ли журналы в резервное копирование;
содержат ли они пользовательский контент.

Без ротации журнал способен заполнить диск и сам стать причиной аварии.

20. После исправления¶

Не ограничивайтесь исчезновением ошибки в журнале.

Повторите пользовательский сценарий.

Например:

ошибка RAG исправлена
    ↓
загрузили новый тестовый файл
    ↓
нашли маркер
    ↓
проверили цитату

Что дальше¶

Для изменений административных прав используйте журнал аудита. Для общего состояния — Состояние системы.