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

394 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 нет потока записей об отказе отправки