Files
mtusi2026lab5/openspec/specs/service-logging/spec.md
T
ricoromaandClaude Opus 5.5 e2a6427c24 feat: add job outbox, relay, leases and image variants to the pipeline
Move publishing out of the upload path: a relay process publishes queued
jobs with confirms. Add lease and attempt fencing, backoff with jitter, a
per-job render process with CPU and memory limits, crop and optimized
variants, the failed registry with audited replay, and staging cleanup.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 15:36:15 +03:00

22 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 вложений.

С лабы 5 записи MUST NOT содержать пароль брокера и тела его сообщений.

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

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 вложения, id задания, размер и тип, а запись об отказе — причину отказа без имени файла

Scenario: Отказ публикации задания

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

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

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

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

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

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

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

Scenario: Очистка staging в журнале

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

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

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

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

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

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

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

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

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

Scenario: Стоимость прохода в итоге

  • WHEN выполняется разовая сверка с --strategy head и --deep
  • THEN итог называет эту стратегию, глубину и предел скорости, затронутые объекты S3, запросы к S3 по операциям, прочитанные байты, сеансы с PostgreSQL и длительность каждого шага, а секретов S3, filename и SHA-256 объектов в журнале нет

Requirement: Журнал worker

Worker (capability attachment-processing) SHALL писать журнал в формате этой capability: JSON-записи в stdout, в каждой instance_id процесса worker и request_id — id обрабатываемого задания. Записи:

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

Записи worker MUST NOT содержать filename вложений, байты объектов, тела сообщений, ключи доступа и секреты S3, пароль брокера и пароль PostgreSQL.

Scenario: Обработка в журнале

  • WHEN worker доводит вложение с уникальным filename F до ready
  • THEN все записи этого задания связаны одним request_id — id задания, в них есть номер попытки, размеры трёх вариантов, длительность и пик памяти процесса обработки, а F и секретов в журнале нет

Scenario: Постоянная ошибка в журнале

  • WHEN вложение стало failed с invalid_image
  • THEN в журнале есть запись warning с id задания и вложения и кодом, без stack trace и байтов

Requirement: Журнал relay и replay

Relay и команда replay (capability job-outbox, attachment-processing) SHALL писать журнал в формате этой capability: JSON-записи в stdout, в каждой instance_id процесса. Записи relay:

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

Записи replay: каждое задание реестра в показе — id задания и вложения, код, причина, число попыток и время; выполненный replay — те же поля и оператор, уровень info; отказ — id и причина отказа, уровень warning; итог прохода — сколько показано, выполнено и отказано.

Записи MUST NOT содержать filename вложений, тела сообщений и секреты.

Scenario: Проход relay в журнале

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

Scenario: Replay в журнале

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