Files
mtusi2026lab4/openspec/specs/service-logging/spec.md
T

13 KiB
Raw Blame History

service-logging Specification

Purpose

Журнал сервиса для диагностики и защиты: структурированные JSON-записи в stdout, связь каждой записи с HTTP-запросом через request_id и запрет на содержимое сообщений и личные данные в логах.

Requirements

Requirement: JSON-записи в stdout

Сервис SHALL писать журнал в stdout, по одному JSON-объекту на строку. Каждая запись SHALL содержать timestamp (ISO 8601 UTC), level и event. Записи HTTP-сервера о запуске и остановке SHALL идти в том же формате. Уровень подробности SHALL задаваться параметром [app] log_level.

Scenario: Каждая строка — JSON

  • WHEN сервис запускается, обслуживает запросы и останавливается
  • THEN каждая строка stdout разбирается как JSON-объект с timestamp, level и event

Scenario: Уровень из настроек

  • WHEN APP__LOG_LEVEL=WARNING
  • THEN записей уровней debug и info от кода сервиса нет

Requirement: Связь записей с запросом

Каждая запись, сделанная при обработке запроса, SHALL содержать request_id, равный заголовку X-Request-Id ответа, и user_id, если пользователь идентифицирован.

Scenario: Поиск по request_id

  • WHEN клиент получил ответ с X-Request-Id = R
  • THEN все записи этого запроса содержат request_id = R

Requirement: Экземпляр в каждой записи

Каждая запись журнала SHALL содержать поле instance_id, равное значению X-Instance-Id процесса. Это относится и к записям вне запроса, в том числе к записям HTTP-сервера о запуске и остановке. Тогда в общем журнале нескольких реплик видно, какая реплика сделала запись.

Scenario: Поиск по реплике

  • WHEN клиент получил ответ с X-Instance-Id = I и X-Request-Id = R
  • THEN все записи запроса R содержат instance_id = I, и записи о запуске и остановке этого процесса тоже содержат instance_id = I

Requirement: Одна итоговая запись на запрос

Для каждого запроса, кроме health, сервис SHALL писать одну итоговую запись с методом, шаблоном пути, статусом и длительностью обработки.

Scenario: Запрос к API

  • WHEN клиент выполняет GET /api/v1/chats/{id}
  • THEN есть итоговая запись с путём /api/v1/chats/{chat_id}, статусом и длительностью

Scenario: Health не шумит

  • WHEN healthcheck вызывает /health/ready каждые несколько секунд
  • THEN итоговых записей для этих запросов нет

Requirement: Без содержимого сообщений и личных данных

Записи MUST NOT содержать текст сообщений, display_name, названия чатов, значения username, тела запросов и ответов. Записи MUST NOT содержать пароли, токены сессий, их хэши, значение заголовка Authorization, значение Idempotency-Key и параметры SQL-запросов. Для сообщений допускаются идентификаторы и длина текста. Повтор отправки SHALL быть виден по признаку повтора и id сообщения. Для сессий допускаются id сессии и user_id.

С лабы 4 записи MUST NOT содержать:

  • ключи доступа и секретные ключи S3;
  • ключ подписи служебных вызовов S3;
  • подписи запросов к S3: их заголовок Authorization и параметры подписи;
  • байты объектов;
  • filename вложений.

Для обращений к S3 допускаются адрес S3, имя bucket, ключ объекта, размер, длительность и класс ошибки. Для вложений допускаются id вложения и чата, размер, тип, ширина и высота изображения, длина filename и причина отказа в загрузке.

Scenario: Отправка сообщения

  • WHEN участник отправляет сообщение с текстом T
  • THEN ни одна запись журнала не содержит T, а запись о создании сообщения содержит его id, chat_id и длину текста

Scenario: Повтор с ключом

  • WHEN участник отправляет сообщение с ключом K, повторяет запрос, а затем шлёт с K другое тело
  • THEN ни одна запись журнала не содержит K; запись о повторе содержит id исходного сообщения и признак повтора, а ответ 409 виден в итоговой записи запроса

Scenario: Вход и выход

  • WHEN пользователь регистрируется с паролем P, входит, получает токен T и выходит, а затем кто-то пытается войти с неверным паролем
  • THEN ни одна запись журнала не содержит P, T, хэш T и значение Authorization; записи о создании и отзыве сессии содержат user_id и id сессии, а неудачный вход записан с уровнем warning без username и пароля

Scenario: Обращение к S3

  • WHEN сервис стартует, затем обращается к S3 сначала с верным, а потом с неверным секретом API
  • THEN ни одна запись журнала не содержит ключ доступа, секрет и подпись запроса; запись о старте содержит адрес S3 и имя bucket, а отказ в учётных данных записан с уровнем error

Scenario: Загрузка вложения

  • WHEN участник загружает изображение с уникальным filename F, а затем повреждённый файл с тем же именем
  • THEN ни одна запись журнала не содержит F; запись о загрузке содержит id вложения, размер и тип, а запись об отказе — причину отказа без имени файла

Requirement: Непредвиденные ошибки в журнале

Непредвиденное исключение SHALL записываться с уровнем error, traceback и request_id запроса.

Scenario: Исключение в обработчике

  • WHEN обработка запроса падает с непредвиденным исключением
  • THEN в журнале есть запись error с traceback и request_id ответа 500

Requirement: Журнал уборщика

Уборщик незавершённых загрузок (capability storage-consistency) SHALL писать журнал в формате этой capability: JSON-записи в stdout, в каждой instance_id процесса уборщика. Записи:

  • старт — интервал, grace, размер выборки, адрес S3, bucket и имя базы;
  • каждая убранная загрузка — id вложения, ключ объекта и возраст загрузки;
  • проход, который убрал хотя бы одну загрузку или прервался отказом хранилища, — сколько убрано, сколько пропущено (их держит другой процесс), причина прерывания и длительность;
  • отказ S3 или PostgreSQL — уровень warning, непредвиденная ошибка — error с traceback;
  • остановка процесса.

Проход, которому нечего убирать, SHALL писаться не выше уровня debug. Записи уборщика MUST NOT содержать ключи доступа и секреты S3, ключ подписи, подписи запросов, filename вложений и байты объектов.

Scenario: Проход уборщика

  • WHEN уборщик убирает незавершённую загрузку
  • THEN в журнале есть запись с id вложения, ключом объекта и возрастом и запись прохода с числом убранных, а секретов S3 и filename в журнале нет

Scenario: Отказ S3 во время прохода

  • WHEN S3 остановлен, а уборщику есть что убирать
  • THEN в журнале запись уровня warning о прерванном проходе с причиной, без секретов, а метаданные загрузки на месте

Requirement: Журнал сверки

Сверка bucket и БД (capability storage-consistency) SHALL писать в журнал процесса уборщика JSON-записи в формате этой capability, в каждой — instance_id процесса. Записи:

  • запись о старте уборщика дополнительно называет интервал сверки, размер страницы и предел изменений;
  • каждое найденное расхождение — класс, ключ объекта, id вложения, если он известен, возраст, размеры объекта и метаданных, если они разные. Уровень warning, если расхождение осталось, и info, если проход с --apply его исправил, с названием действия;
  • итог прохода — режим, сколько объектов и строк просмотрено, сколько найдено и исправлено по классам, сколько свежих и уже помеченных, длительность и причина прерывания. Уровень info, если расхождений не осталось, иначе warning;
  • превышение предела изменений — error с числом изменений и пределом;
  • отказ S3 или PostgreSQL — warning, непредвиденная ошибка — error с traceback.

Если расхождений за проход больше тысячи, отдельными записями SHALL писаться только первые, а итог SHALL называть, сколько осталось без записи. Скачивание потерянного оригинала реплика API SHALL писать записью уровня info с id вложения и ключом объекта, а не error. Записи сверки MUST NOT содержать ключи доступа и секреты S3, ключ подписи, подписи запросов, filename вложений и байты объектов.

Scenario: Журнал разового прохода

  • WHEN сверка находит объект без метаданных и метаданные без объекта, а затем исправляет их с --apply
  • THEN результат такой:
    • в журнале dry-run — две записи warning с классом, ключом и возрастом и итог warning;
    • в журнале прохода с --apply — две записи info с действием и итог info;
    • секретов S3 и filename в журнале нет

Scenario: Предел изменений в журнале

  • WHEN сверка с --apply отказывается исправлять из-за предела
  • THEN в журнале запись error с числом изменений и пределом, а итог прохода — warning