Files
mtusi2026lab6/openspec/specs/service-logging/spec.md
T
2026-11-11 21:04:40 +03:00

28 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 и секретов нет

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

При включённой телеметрии (capability observability, «Где телеметрия включена») запись журнала API, worker или relay, сделанная при активном span, SHALL содержать trace_id (32 шестнадцатеричных символа) и span_id (16 символов) этого span — и в stdout, и в записи, отправленной в хранилище логов. Это записи обработки запроса, кроме health, в том числе итоговая запись о запросе, и записи обработки доставки worker. У задания с сохранённым контекстом доставка идёт в трассе загрузки (capability observability, «Сквозная трасса загрузки и обработки»): её записи содержат trace_id трассы загрузки этого вложения. Записи вне span — старт, остановка, health, фоновые циклы, проходы relay — этих полей MUST NOT содержать. request_id остаётся прежним: trace_id его не заменяет (contracts/observability.md).

Scenario: Записи запроса ведут к трассе

  • WHEN клиент получил ответ с X-Request-Id R, а телеметрия включена
  • THEN все записи stdout с request_id R, включая итоговую запись о запросе, содержат один и тот же trace_id T и span_id, а трасса T в Tempo — трасса этого запроса

Scenario: Записи задания ведут к трассе

  • WHEN worker довёл вложение до ready
  • THEN записи этого задания («Started job attempt», «Attachment became ready») содержат trace_id трассы обработки задания — того же значения, что у записи «Uploaded attachment» его загрузки, если у задания был сохранённый контекст

Scenario: Проход relay без полей трассы

  • WHEN relay публикует задание загрузки
  • THEN его запись о проходе не содержит trace_id и span_id, хотя span producer этой публикации есть в трассе загрузки

Scenario: Без телеметрии полей нет

  • WHEN телеметрия выключена, и клиент выполняет запрос
  • THEN записи журнала не содержат trace_id и span_id, а остальные поля прежние

Requirement: Журнал в хранилище логов

При включённой телеметрии каждая запись журнала API, worker и relay, которая пишется в stdout между запуском SDK и началом его закрытия при остановке, SHALL ещё и отправляться в хранилище логов через Collector; записи до запуска SDK (записи uvicorn до lifespan, остановка до старта, ошибки настроек) и после начала закрытия (записи «Stopped worker» и «Stopped relay») идут только в stdout. Отправленная запись: тело — event, уровень — из level, время — timestamp, остальные поля записи — атрибутами, ресурс — service.name и остальные атрибуты процесса (capability observability, «SDK в API и worker» и «SDK в relay»). Записи stdout при этом MUST NOT меняться, кроме полей трассы (требование «Связь записей с трассой»). Записи самого SDK OpenTelemetry идут только в stdout. Отказ отправки MUST NOT задерживать запись и обработку и MUST NOT терять записи stdout.

В хранилище записи SHALL искаться по сервису и экземпляру (метки потока) и по полям записи, в том числе request_id, attachment_id, trace_id. Требование «Без содержимого сообщений и личных данных» действует на отправленные записи так же, как на stdout.

Scenario: Запись в Loki совпадает со stdout

  • WHEN клиент получил ответ с X-Request-Id R и X-Instance-Id I
  • THEN в Loki есть итоговая запись о запросе с service_name = messenger-api, request_id R, instance_id I, тем же event, методом, шаблоном пути, статусом и длительностью, что в stdout реплики, и с тем же trace_id

Scenario: Записи relay в Loki

  • WHEN relay публикует задание загрузки
  • THEN в Loki есть его запись о проходе с service_name = messenger-relay, тем же event и числом опубликованных, что в stdout relay

Scenario: Ошибка с traceback в Loki

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

Scenario: Отказ отправки журнала

  • WHEN Collector остановлен, и клиент выполняет запросы
  • THEN все записи этих запросов есть в stdout, ответы прежние, а в stdout нет потока записей об отказе отправки