- reconcile --strategy head, --deep (checksum_mismatch), restore needs the same SHA-256 - [reconciler] max_objects_per_second (2000), pause interrupted by signal - --apply stops rechecks once the limit is exceeded (unchecked) - pass cost in the summary: S3 objects and requests, bytes, DB sessions, phases - S3 client counters, cleaner exits with os._exit after main() - fault tests, hook args, driver reconcile-signal --pace - bench profile reconcile / reconcile_quick: fill outside the API, gateway metrics, background load - sync spec deltas, rules, AGENTS.md, PLAN.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
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 участник загружает изображение с уникальным
filenameF, а затем повреждённый файл с тем же именем - 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его исправил, с названием действия; - итог прохода — режим, стратегия, глубина, предел скорости, сколько
объектов и строк просмотрено, сколько найдено и исправлено по классам,
сколько свежих и уже помеченных, сколько кандидатов не перепроверено,
длительность и причина прерывания. Ещё итог называет стоимость
прохода: сколько объектов 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в журнале нет
- в журнале dry-run — две записи
Scenario: Предел изменений в журнале
- WHEN сверка с
--applyотказывается исправлять из-за предела - THEN в журнале запись
errorс пределом, числом подтверждённых изменений и числом неперепроверенных кандидатов, а итог прохода —warning
Scenario: Стоимость прохода в итоге
- WHEN выполняется разовая сверка с
--strategy headи--deep - THEN итог называет эту стратегию, глубину и предел скорости,
затронутые объекты S3, запросы к S3 по операциям, прочитанные байты,
сеансы с PostgreSQL и длительность каждого шага, а секретов S3,
filenameи SHA-256 объектов в журнале нет