Контракт диагностического логирования и его реализация (
core/diag_log.py+ инструментированиеdownloader.py/stepik_client.py/oauth_flow.py/diagnostic_stepik.py). Описывает, когда пишется лог, что в него попадает, требования редакции секретов и политику opt-in/opt-out.Единый логгер живёт в
core/diag_log.py:get_logger(name)для модулей,configure_diagnostics(level)для активации,register_secret()иredact()для маскирования. Обычный вывод по-прежнему идёт через_console(rich); этот логгер — отдельный диагностический канал, включаемый по запросу. Включение: флаг--diagnosticCLI, переменнаяSTEPIK_GRADER_LOG=debug|info|offили запускpython -m stepik_grader.diagnostic_stepik(там debug включён).
Проблемы воспроизводятся у пользователя, а не у мейнтейнера: сеть, OAuth, парсинг ответов Stepik, раскладка тест-кейсов. Нужен способ получить подробный след по явному запросу, не засоряя обычный вывод и не рискуя утечкой токена. Диагностический режим — это управляемая многословность плюс опциональный лог-файл.
По умолчанию — тихо. Обычный запуск пишет только пользовательский вывод
через _console; диагностический лог выключен (opt-in), файл не создаётся.
Способы включения — все три реализованы (любой из):
| Способ | Область | Пример |
|---|---|---|
| Флаг CLI | один запуск | --diagnostic |
| Переменная окружения | сессия/CI | STEPIK_GRADER_LOG=debug |
| Диагностическая утилита | разбор API/токена | python -m stepik_grader.diagnostic_stepik |
Уровни: warning (дефолт видимого вывода) → info → debug (полный след:
URL-запросы без секретов, шаги парсинга, пути файлов). Повышение уровня — только
явным opt-in; понижать/выключать (opt-out) можно тем же флагом/переменной
(напр. STEPIK_GRADER_LOG=off).
- Путь по умолчанию: внутри диагностического каталога
(
stepik_diagnostics/, уже используетсяdiagnostic_stepik.py) — напр.stepik_diagnostics/grader.log. Каталог держится в.gitignore(какerrors.txt,.grader_cache/— см. project-structure.md). - Создаётся только при включённом диагностическом режиме (opt-in). Без него файл не появляется — «чистый» запуск не оставляет следов на диске.
- Формат: строки с меткой времени и уровнем; человекочитаемо, без обязательного JSON (тяжёлых зависимостей не вводить — CLAUDE.md).
- Не сделано: ротация и потолок размера. Файл растёт, пока включён режим — при долгих диагностических сессиях его чистит пользователь. Это единственный незакрытый пункт документа; всё остальное здесь описывает реализованное поведение, а не замысел.
- Не коммитить. Лог-файл и
stepik_diagnostics/— локальные артефакты; вставлять их в issue/PR можно только после проверки на секреты (см. ниже).
Диагностический лог — самая частая точка утечки токена. Требования жёсткие (в скоупе SECURITY.md):
- Никогда не логировать содержимое
secrets.json,access_token,refresh_token,client_secret, заголовокAuthorization/Bearer .... - Редактировать при выводе, а не полагаться на «не передавать». Значения
токенов заменяются на
***redacted***(или маскируются до последних 4 символов) в любом сообщении — включая эхо URL, заголовков и тел ответов Stepik. Редакция применяется на уровне логгера, до записи в файл/консоль. - URL с query-параметрами токена санитизируются (вырезать
access_token=/code=). - Отчёты диагностики (
stepik_diagnostics/*.json,save_jsonвdiagnostic_stepik.py) подпадают под те же правила — не сохранять токен в payload. - Тест на редакцию — реализован (
tests/test_diag_log.py): unit-проверки, что известные секрет-поля (Bearer-заголовок, query-токены, JSON-поля,register_secret-значения) не попадают в лог-строки.
Утечка токена в лог/отчёт/кэш прямо перечислена в скоупе безопасности (SECURITY.md § Область) — редакция закрывает именно её.
Пункты выше касаются мест, о которых мы уже знаем. Проблема в том, что следующая точка дампа появится не по злому умыслу: автор функции, сохраняющей ответ API, просто не будет знать, что обязан был подумать о редакции — ровно так и появился отчёт диагностики, писавший ответы API на диск как есть.
Поэтому перечень точек проверяется машинно —
python scripts/check_secret_dumps.py (CI, job docs-guardrails). Проверка
обходит модули пакета, работающие с сетью или OAuth, находит в них записи файлов
и требует, чтобы каждая была в реестре KNOWN_DUMPS с причиной, по которой
секрет туда не попадёт. Точка, помеченная как редактирующая, обязана вызывать
redact в своём теле; запись реестра, которой больше не соответствует ни одна
точка, удаляется — протухший реестр ничего не утверждает.
Кэш ответов API (.stepik_cache/) — единственное место, где ответ ложится на
диск целиком, а не отобранными полями. Он не редактируется, а отказывается
кэшировать ответ, в котором редакция что-то изменила бы: подставить
***redacted*** в тело ответа значит отдать вызывающей стороне испорченные
данные — текст задачи со словом «password» уехал бы в файлы курса покалеченным.
Кэш либо чист, либо его нет.
Диагностика касается сетевого/OAuth-слоя; правила выше реализованы в:
core/stepik_client.py— логирование HTTP-запросов/ответов Stepik наdebugс санитизацией URL/заголовков.core/oauth_flow.py— шаги авторизации без утечкиclient_secret/токена.downloader.py— след разбора URL шага, раскладки файлов, извлечения тест-кейсов (какой из 4 источников сработал — ZIP/HTML/GitHub/ничего).diagnostic_stepik.py— пишет отчёты вstepik_diagnostics/и подключён к общему логгеру (configure_diagnostics("debug", …)) с теми же правилами редакции.
Единый логгер должен оставаться совместимым с _console-fallback (rich
опционален) и не добавлять зависимостей. Вывод бизнес-модулей — по-прежнему
через _console, а не голый print() (CLAUDE.md).
- Не вводить внешние logging-фреймворки/агрегаторы (stdlib
loggingдостаточно). - Не логировать по умолчанию (privacy/скорость) — только opt-in.
- Не менять пользовательский вывод обычного (не диагностического) запуска.