g2s-aggregator/spec/tasks/014_add_minimal_structlog_json_logging.md

id, title, status, created

id	title	status	created
014	Add minimal structlog JSON logging	DONE	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