122 lines
11 KiB
Markdown
122 lines
11 KiB
Markdown
# P29 · 2020-07 · Структурированные логи
|
||
|
||
Статус: **принят в publication registry 31 июля 2026 года**. Registry
|
||
применяет revision по стабильным slug, сохраняя дату и автора базового архива.
|
||
|
||
- <code>editorial-2020-07-practice-structured-logs</code>;
|
||
- <code>editorial-2020-07-mechanism-structured-logs</code>;
|
||
- <code>editorial-2020-07-field-structured-logs</code>.
|
||
|
||
## Рамка и границы утверждений
|
||
|
||
Голос — М3, июль 2020 года. Автор связывает backend, HTTP-границы, delivery и
|
||
диагностику, но не объявляет локальный JSONL-разбор зрелой платформой
|
||
наблюдаемости. В каждой статье логика идёт по маршруту «симптом → причина →
|
||
проверка → действие».
|
||
|
||
Пакет ограничен одним синтетическим HTTP-запросом и его
|
||
<code>request_id</code>. Внутренний <code>X-Request-Id</code> явно назван
|
||
конвенцией конкретного проекта, а не стандартом протокола. Он помогает
|
||
собрать известные записи одного действия, но не создаёт spans, не доказывает
|
||
причинность, не строит critical path и не измеряет SLO.
|
||
|
||
Все id, сервисы, маршруты, JSONL-строки, ошибки, заголовки и команды поиска
|
||
помечены как учебные и синтетические. В примерах нет реальных пользователей,
|
||
production-инцидентов, учётных данных или приватных endpoint.
|
||
|
||
## Pass 1 — факты и техника
|
||
|
||
- RFC 5424 использован как основание для тезиса, что событие выигрывает от
|
||
разделённых, машиночитаемых полей. Статья не утверждает, что её JSON
|
||
буквально является сообщением RFC 5424: это разные форматы.
|
||
- RFC 8259 использован для требования валидного JSON. Пример сериализует
|
||
объект через <code>JSON.stringify</code>, а не собирает псевдо-JSON
|
||
строковой конкатенацией.
|
||
- Официальная документация Pino использована только как ссылка на API
|
||
дочернего логгера и <code>redact</code>. Текст требует проверить
|
||
возможности версии, установленной в конкретном проекте; не приписывает
|
||
пакету незафиксированную версию или конфигурацию.
|
||
- OWASP Logging Cheat Sheet сверена для границы чувствительных полей.
|
||
<code>authorization</code>, <code>cookie</code>, <code>password</code>,
|
||
<code>token</code> и <code>secret</code> не выводятся в учебном fixture в
|
||
исходном виде.
|
||
- Детерминированный fixture проверяет семь обязательных полей, формат
|
||
синтетического <code>request_id</code> и redaction двух учебных
|
||
placeholder-значений. Он не выполняет HTTP-запрос, не читает production
|
||
журнал и не моделирует конкурентную нагрузку.
|
||
- Словарь <code>event</code>, шаблон <code>route</code>, различие
|
||
<code>request_id</code>/<code>operation_id</code>, redaction до
|
||
сериализации и высокая кардинальность request_id описаны без вывода, что
|
||
они уже измеряются в реальном контуре.
|
||
- Вердикт: технические утверждения имеют источники, учебный пример проверяем
|
||
локально и ограничения не скрыты.
|
||
|
||
## Pass 2 — редактура и голос
|
||
|
||
- Первые два абзаца каждой статьи называют наблюдаемый сбой и цену: ложный
|
||
диагноз по времени, разрыв между сервисами, лишние данные и бесконечный
|
||
словарь значений.
|
||
- Три текста отвечают на разные вопросы: практика задаёт контракт события;
|
||
механизм проводит один request_id через границы; разбор выбирает поля,
|
||
redaction и правило кардинальности.
|
||
- Речь не заменяет решение оценками. Каждый существенный тезис связан с
|
||
проверкой: форма JSON, одноимённый request_id в трёх записях, точный
|
||
redacted output, шаблон маршрута или нормализованный error code.
|
||
- Draft gate подтверждает объём основного текста 11 512 / 10 845 / 11 529
|
||
знаков. Внутренняя проверка чистой прозы без таблиц, рисунков и кода:
|
||
8 421 / 8 092 / 8 514 знаков; это соответствует целевому коридору П29
|
||
7–9 тыс. знаков.
|
||
- В каждом тексте есть доступная таблица с <code>caption</code> и
|
||
<code>thead</code>, figure, JSON или JavaScript-пример, нумерованный
|
||
маршрут и четыре официальных/первичных источника.
|
||
- Вердикт: статьи достаточно развёрнуты, но не выдают поздний опыт
|
||
observability-платформы за практику автора в 2020 году.
|
||
|
||
## Pass 3 — визуал и выпуск
|
||
|
||
- Для практики создана вертикальная схема контракта события: базовые поля,
|
||
идентификатор, локальный контекст и redaction до stdout.
|
||
- Для механизма создан маршрут gateway → дочерний логгер и заголовок →
|
||
catalog API → учебный JSONL-поиск. В подписи и самом рисунке прямо
|
||
сказано, что это не trace critical path.
|
||
- Для разбора создано дерево решения: диагностический вопрос, чувствительное
|
||
значение, высокая кардинальность, безопасный контекст и финальный
|
||
синтетический запрос.
|
||
- Все SVG используют title, desc, встроенный текст и фигуры без скриптов,
|
||
внешних изображений или растровых заменителей. Каждый отрендерен Sharp на
|
||
ширине 375 px: вертикальная компоновка сохранилась, текста и рамки не
|
||
обрезаются, горизонтальный overflow не обнаружен.
|
||
- У фигур в статьях есть содержательные alt-тексты и подписи. Узкие таблицы
|
||
помещены в <code>table-scroll</code>; в коде каждой таблицы есть
|
||
<code>caption</code>, <code>thead</code> и <code>scope="col"</code>.
|
||
- Основной редактор повторно просмотрел финальные PNG на 375 px. После
|
||
подключения registry strict audit и production build пройдены; browser-review
|
||
и assistive-technology проверка не выполнялись и не подменяются сборкой.
|
||
- Вердикт: тройное ревью пройдено; статические выпускные проверки не выданы за
|
||
реальную проверку внешнего лог-коллектора.
|
||
|
||
## Выполненные проверки
|
||
|
||
| Проверка | Команда | Результат |
|
||
| --- | --- | --- |
|
||
| Node syntax | <code>node --check scripts/upgrade-2020-07.mjs</code> из <code>web/</code> | успешно |
|
||
| JSON-only CLI и import-safe export | <code>npm run audit:draft -- scripts/upgrade-2020-07.mjs</code> из <code>web/</code> | успешно: 11 512 / 10 845 / 11 529 body chars |
|
||
| Контрактный fixture | <code>node scripts/upgrade-2020-07.mjs --run-fixture</code> из <code>web/</code> | успешно: 7 обязательных полей, <code>req-demo-20200714-01</code>, <code>[REDACTED]</code> |
|
||
| XML | <code>xmllint --noout public/assets/editorial/2020/structured-log-event-2020.svg public/assets/editorial/2020/structured-log-correlation-2020.svg public/assets/editorial/2020/structured-log-diagnosis-2020.svg</code> из <code>web/</code> | успешно |
|
||
| Мобильный preflight | Sharp render всех трёх SVG на ширине 375 px | просмотрено вручную: без обрезания и горизонтального overflow |
|
||
| Strict audit после подключения registry | PASS: 11 512 / 10 845 / 11 529 знаков; 2 table и 2 code example у каждой revision |
|
||
| <code>npm run build</code> | PASS, code 0, 374 статические страницы |
|
||
| Scope/self-review | PASS: в revision нет <code>date</code>/<code>author</code>, <code>articles.json</code> не перезаписан |
|
||
|
||
## Ограничения автономной партии
|
||
|
||
- <code>articles.json</code>, редакционный стандарт, очередь и package config
|
||
не перезаписывались; registry заменяет только редакционные поля.
|
||
- Browser, CI, Docker, HTTP-сервер и внешний лог-коллектор не запускались.
|
||
- Учебный JSONL-запрос показывает корреляцию известных событий; он не
|
||
доказывает доставку журналов, порядок параллельных операций или
|
||
производительность реального контура.
|
||
|
||
Выпусковой вердикт: **пакет принят к публикации**. Публикационный слой не
|
||
означает, что учебная корреляция была проверена на реальных событиях.
|