394 lines
28 KiB
Markdown
394 lines
28 KiB
Markdown
# 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 нет потока записей об отказе отправки
|