014 add json logging

2026-03-13 17:19:03 +03:00
parent 2bd884c8d5
commit 7c5be003c1
10 changed files with 224 additions and 14 deletions
@@ -0,0 +1,44 @@
+---
+id: 014
+title: Add minimal structlog JSON logging
+status: DONE
+created: 2026-03-12
+---
+
+## Context
+После удаления observability stack приложение осталось без централизованной конфигурации логирования. При этом в runtime-коде есть локальная настройка `logging.basicConfig(...)`, а новое требование состоит в том, чтобы все runtime-логи приложения выводились в JSON без возврата tracing, metrics и alerting.
+
+## Goal
+Подключить минимальную централизованную настройку `structlog`, чтобы runtime-логи приложения и Uvicorn выводились как JSON-объекты, а прикладные модули использовали общий logging setup вместо локальной конфигурации.
+
+## Constraints
+- Соблюдать layered architecture из `AGENTS.md`.
+- Scope задачи: только logging wiring, JSON formatting и интеграция существующих logger calls.
+- `structlog` использовать только для JSON logging; не добавлять `request_id`, `trace_id`, OpenTelemetry, metrics, SigNoz, Telegram и иные observability features.
+- Конфигурация логирования должна быть централизована на уровне app startup или отдельного runtime-модуля; в Controller, Service, Repository, Adapter и Business Logic запрещено вызывать `logging.basicConfig(...)`.
+- Не изменять API contract, business rules, provider protocol, cache behavior и логику обработки ошибок.
+- используй context7, чтобы узнать контракт текущей версии пакета structlog
+
+## Acceptance criteria
+- При старте приложения выполняется единая инициализация logging на базе `structlog`.
+- Логи приложения и `uvicorn.error`/`uvicorn.access` сериализуются в JSON, одна запись на строку.
+- Каждая лог-запись содержит как минимум поля `event`, `level`, `timestamp` и `logger`.
+- В прикладных модулях отсутствуют локальные вызовы `logging.basicConfig(...)` и текстовые formatter-конфигурации для runtime logging.
+- Добавлен тест, который валидирует emitted log line как корректный JSON и проверяет обязательные поля.
+
+## Definition of Done
+- [ ] Добавлена централизованная конфигурация JSON logging на базе `structlog`.
+- [ ] Удалены локальные настройки logging из прикладных модулей.
+- [ ] `uvicorn.error` и `uvicorn.access` подключены к тому же JSON logging setup.
+- [ ] Добавлены или обновлены тесты для logging bootstrap и JSON serialization.
+- [ ] Пройдены все команды из раздела Commands.
+
+## Tests
+- Добавить `tests/logging/test_json_logging.py` для проверки JSON serialization и обязательных полей лог-записи.
+- Обновить `tests/smoke/test_app_import.py` для проверки вызова централизованного logging bootstrap при создании app.
+- При изменении конфигурации Uvicorn loggers добавить тест на `uvicorn.error` и `uvicorn.access` без запуска реального сервера.
+
+## Commands
+- `poetry run pytest tests/logging/test_json_logging.py -q`
+- `poetry run pytest tests/smoke/test_app_import.py -q`
+- `poetry run pytest tests/adapters/delivery_providers/cdek/test_client.py -q`