Skip to content

Latest commit

 

History

History
130 lines (106 loc) · 10.1 KB

logging.md

File metadata and controls

130 lines (106 loc) · 10.1 KB

Диагностический режим и лог-файл

Контракт диагностического логирования и его реализация (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); этот логгер — отдельный диагностический канал, включаемый по запросу. Включение: флаг --diagnostic CLI, переменная STEPIK_GRADER_LOG=debug|info|off или запуск python -m stepik_grader.diagnostic_stepik (там debug включён).

Зачем отдельный диагностический режим

Проблемы воспроизводятся у пользователя, а не у мейнтейнера: сеть, OAuth, парсинг ответов Stepik, раскладка тест-кейсов. Нужен способ получить подробный след по явному запросу, не засоряя обычный вывод и не рискуя утечкой токена. Диагностический режим — это управляемая многословность плюс опциональный лог-файл.

Уровни и активация (opt-in)

По умолчанию — тихо. Обычный запуск пишет только пользовательский вывод через _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):

  1. Никогда не логировать содержимое secrets.json, access_token, refresh_token, client_secret, заголовок Authorization/Bearer ....
  2. Редактировать при выводе, а не полагаться на «не передавать». Значения токенов заменяются на ***redacted*** (или маскируются до последних 4 символов) в любом сообщении — включая эхо URL, заголовков и тел ответов Stepik. Редакция применяется на уровне логгера, до записи в файл/консоль.
  3. URL с query-параметрами токена санитизируются (вырезать access_token=/code=).
  4. Отчёты диагностики (stepik_diagnostics/*.json, save_json в diagnostic_stepik.py) подпадают под те же правила — не сохранять токен в payload.
  5. Тест на редакцию — реализован (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).

Non-goals

  • Не вводить внешние logging-фреймворки/агрегаторы (stdlib logging достаточно).
  • Не логировать по умолчанию (privacy/скорость) — только opt-in.
  • Не менять пользовательский вывод обычного (не диагностического) запуска.