Field guide · operations
Структурированные логи без runtime-зависимостей?
Короткий ответ
Нужны не только JSON-вызовы, а пять явных контрактов: стабильный NDJSON envelope, контекст через child logger, redaction до доставки, ограниченная политика backpressure и закрытие root logger после остановки входящего трафика. swm-logs 0.1.1 реализует форматирование и lifecycle; хранение, retries и сетевую доставку оставляет приложению.
- NDJSON
- формат
- 5
- явных контрактов
- 64 КиБ
- buffer default
Границы ответа
Рекомендация подходит для native ESM на Node.js 22/24. «Ноль зависимостей» относится к runtime-зависимостям пакета, а не отменяет внешнюю систему сбора логов.
Минимальный контракт структурированного логирования
| Задача | Контракт | Проверка |
|---|---|---|
| Событие | Одна JSON-запись на строку; level, time и msg имеют стабильные типы. | Парсер читает поток построчно без многострочных исключений. |
| Контекст | Child logger наследует service/request bindings без мутации родителя. | requestId присутствует во всех событиях запроса и не течёт в соседний запрос. |
| Секреты | Точные и wildcard paths редактируются до formatter и transport. | Тесты покрывают token, password и динамические headers/cookies. |
| Backpressure | Immediate mode допустим только без строгого лимита; иначе нужен bounded transport. | Известны max queue, overflow policy и счётчик потерь. |
| Shutdown | Сначала остановить новые запросы, затем drain, потом await rootLogger.close(). | Интеграционный тест подтверждает доставку последнего события. |
| Crash path | fatal + flushSync(); durable гарантия требует file descriptor или транспорта с собственной гарантией. | Отдельный процесс-тест аварийно завершается и проверяет последнюю строку. |
Минимальная production-конфигурация
- 01
Логи собирает stdout-агент платформы
Начните с immediate outputНо считайте очередь Node.js stream и не называйте её bounded.
- 02
Потери должны быть ограничены и измеримы
Напишите bounded transportЗафиксируйте размер очереди, overflow policy, retries и независимую метрику потерь.
- 03
Нужна гарантированная локальная запись
Используйте file descriptorПроверьте flushSync() и отдельно решите ротацию и retention.
Границы решения
- Logger не заменяет log collector, storage, retention и alerting.
- Красивый вывод относится к development pipeline и не должен менять production envelope.
- Секреты нельзя защищать только списком полей: schema и redaction tests должны развиваться вместе.
Проверяемый контракт
Страница основана на опубликованной версии пакета и её зафиксированном README.