# 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`. #### 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 и пароля ### Requirement: Непредвиденные ошибки в журнале Непредвиденное исключение SHALL записываться с уровнем `error`, traceback и `request_id` запроса. #### Scenario: Исключение в обработчике - **WHEN** обработка запроса падает с непредвиденным исключением - **THEN** в журнале есть запись `error` с traceback и `request_id` ответа 500