[GOV-OBS-012] Внедрить структурированное JSON-логирование для ClickHouse

Перевод stdout шлюза на JSON Lines для интеграции с Vector и ClickHouse

NoteКраткая карточка задачи

• Репозиторий / Компонент: gov-registry-gateway (Go / SOAP Ingress).
• Тип задачи: Инфраструктурная / Обсервабилити (Observability).
• Справочник ошибок: [Раздел 5. Справочник ошибок технической документации]
• Статус: Готово к реализации

---

• Инструкция по шагам:
  1. Удаление текстовых логов: Полностью удалить из кодовой базы стандартные вызовы log.Println и log.Fatalf после инициализации БД. Логирование в os.Stdout должно содержать строго одну валидную JSON-строку на одно событие (формат JSON Lines).
  2. Подключение логгера: Интегрировать структурированный логгер (рекомендуется встроенный slog из Go 1.21+ или uber-go/zap). Текстовые примеси в потоке вывода запрещены, так как они ломают сборщик логов Vector.
  3. Формирование базовых полей: Настроить автоматическую генерацию полей для каждого события: timestamp (в формате RFC3339 Nano), level (INFO, WARN, ERROR, FATAL) и ui_payload (для данного сервиса всегда передавать null).
  4. Реализация логирования бизнес-ошибок (На Шаге 7 и Шаге 13): При возникновении нештатных ситуаций или отказов авторизации, формировать корневое поле canonical_code и вложенный объект observability_json в точном соответствии со справочником ошибок:
     • При невалидном/отозванном токене: canonical_code: "GOV_AUTH_DENIED", в transport_statuses передавать {"grpc": 16, "http": 401}, а в observability_json.labels указывать причину token_invalid_or_revoked.
     • При отсутствии записи в реестре: canonical_code: "DB_EMPLOYEE_NOT_FOUND", в transport_statuses передавать {"grpc": 5, "http": 200}, а в метрику отправлять ярлык user_id_absent.
  5. Логирование критических сбоев СУБД: В блоке обработки системных ошибок соединения с PostgreSQL формировать лог с уровнем FATAL, кодом DB_GOV_POSTGRES_DOWN, статусами {"grpc": 14, "http": 500} и таргетом INTERNAL_SYSTEM. Внутри меток ClickHouse передавать точное имя базы данных gov_registry_db.
  6. Логирование успешных запросов (На Шаге 15): При успешной отдаче персональных данных сотрудника формировать лог со значением canonical_code: "SUCCESS", уровнем INFO и статусами {"grpc": null, "http": 200}.

5. Справочник ошибок и Обсервабилити (ClickHouse / UI Logs)

Для обеспечения сквозного мониторинга (Observability), анализа качества интеграции и сбора метрик в ClickHouse, каждая нештатная ситуация классифицируется по внутреннему коду.

При возникновении ошибки сервис формирует структурированный лог, содержащий контекст для внешних систем и метрики для аналитической СУБД.

1. Код (canonical_code)	2. Уровень (log_level)	3. Статусы (transport_statuses)	4. Получатель (error_target)	5. JSON для Фронтенда (ui_payload)	6. Метрики для ClickHouse (observability_json)
GOV_AUTH_DENIED	WARN	{“grpc”: 16, “http”: 401}	EXTERNAL_SYSTEM	null	{“metric”: “auth_fail”, “labels”: {“service”: “gov_gateway”, “reason”: “token_invalid_or_revoked”}}
DB_GOV_POSTGRES_DOWN	FATAL	{“grpc”: 14, “http”: 500}	INTERNAL_SYSTEM	null	{“code”: “DB_GOV_POSTGRES_DOWN”, “metric”: “db_conn_lost”, “labels”: {“db”: “gov_registry_db”}}
DB_EMPLOYEE_NOT_FOUND	INFO	{“grpc”: 5, “http”: 200}	EXTERNAL_SYSTEM	null	{“metric”: “registry_miss”, “labels”: {“service”: “gov_gateway”, “reason”: “user_id_absent”}}
SOAP_XML_BAD_REQUEST	WARN	{“grpc”: 3, “http”: 400}	EXTERNAL_SYSTEM	null	{“metric”: “contract_fail”, “labels”: {“validator”: “go_xml_unmarshal”}}