Files
plba_v2/openspec/specs/observability/technical-logging/spec.md
T
alex d517820088
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped
PLBA2-2. Архивация спек
2026-10-10 20:55:13 +03:00

45 lines
3.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Capability: Техническое логирование
## Purpose
Формировать единые технические JSON-логи в stdout с application_id и business_trace_id.
## Границы
- В capability входят контракт JSON-записи технического лога и её вывод через stdlib StreamHandler в stdout. Хранение и доставка логов находятся за пределами capability.
## Requirements
### Requirement: Структурированные технические логи
**ID:** `OBS.TL-01`
PLBA2 SHALL задавать контракт технической JSON-записи и передавать её в stdout.
#### Scenario: Сокращенный use case: техническая запись
##### Основной поток
1. Описываем поля отправляемой записи по [OBS.TL-01.FR-01](#obstl-01fr-01-api-контракт-сообщения-технической-записи).
2. Фиксируем контекст и вывод записи в stdout по [OBS.TL-01.FR-02](#obstl-01fr-02-контекст-и-передача-в-stdout).
#### Функциональные требования
##### OBS.TL-01.FR-01 [API]: Контракт сообщения технической записи
Тип контракта: request
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- |
| `timestamp` | `string` | Обязательное | UTC timestamp; null запрещён | Время формирования записи |
| `level` | `string` | Обязательное | Null запрещён | Уровень технической записи |
| `logger` | `string` | Обязательное | Null запрещён | Имя logger |
| `message` | `string` | Обязательное | Null запрещён | Текст записи |
| `application_id` | `string` | Обязательное | Null запрещён | Идентификатор приложения |
| `attributes` | `object` | Опциональное | Значения должны быть JSON-safe | Структурированные поля записи |
| `business_trace_id` | `string` | Опциональное | Передаётся при установленном business trace context | Связь технической записи с бизнес-историей |
##### OBS.TL-01.FR-02: Контекст и передача в stdout
При установленном контексте formatter добавляет `business_trace_id`; контекст поддерживает async-задачи и использует то же значение, что business trace adapter. JSON кодируется стандартным сериализатором. Приложение направляет formatter в stdlib StreamHandler для stdout. PLBA2 не отправляет технические логи в БД, RabbitMQ, Loki или Grafana; доставку и просмотр обеспечивает платформа.