Перейти к основному содержимому

Что такое спецификация

dagstack/logger-spec — нормативный источник истины для структурированного логирования в экосистеме dagstack. Он фиксирует, что должно соблюдаться в любой имплементации (dagstack/logger-python, dagstack/logger-typescript, dagstack/logger-go) и почему именно это решение принято.

Чем секция «Спецификация» отличается от guide'ов​

СекцияАудиторияЧто даёт
КонцепцииРазработчик приложенияОбъясняет, как логгер работает сегодня в терминах конкретного языка.
РуководстваРазработчик приложенияШаг за шагом проводит через задачу.
Спецификация (этот раздел)Автор имплементации / ревьюерОбъясняет, почему принято решение; фиксирует нормативные гарантии.

ADR​

На v1.0 оформлен один ADR:

  1. ADR-0001: Контракт логгера — формат передачи, уровни, API логгера, приёмники, семантические соглашения, локальные переопределения, конфигурация через config-spec, маскирование, сэмплирование, async / shutdown, conformance.

Дополнительные ADR в очереди на post-pilot бэклог v1.1, включая структурное выделение AI-agent extension pack в отдельный ADR-0002, политику pinning версий OTel GenAI, форматирование stacktrace для исключений и путь deprecation для Progress sink из plugin-system.

Нормативный источник​

Страницы этой секции — описательное прозовое резюме ADR. Формальный нормативный текст живёт в dagstack/logger-spec. Если ты работаешь над изменениями внутри имплементации, читай нормативную версию: она охватывает все пограничные случаи, правила сериализации и требования к conformance-фикстурам.

Как меняется спецификация​

  1. Открой issue в dagstack/logger-spec.
  2. Подай PR с новым ADR или ревизией существующего.
  3. Architect review плюс sign-off от мейнтейнеров каждой имплементации (каждая имплементация подтверждает, что может зашипить изменение).
  4. После merge — обнови имплементации и освежи резюме в этой секции.

Связанные спецификации​