54 lines
12 KiB
Markdown
54 lines
12 KiB
Markdown
# П67 · 2023-09 · Логи, метрики и трассы — три прохода саморевью
|
||
|
||
## Рамка пакета
|
||
|
||
- Slug: `editorial-2023-09-practice-telemetry-signals`, `editorial-2023-09-mechanism-telemetry-signals`, `editorial-2023-09-field-telemetry-signals`.
|
||
- Голос: М6, сентябрь 2023 года. Автор работает как системный практик: начинает с несвязанного сигнала и цены ошибочного решения, строит маленький контракт данных, отделяет проверяемое от неизвестного и оставляет владельцу следующий шаг. Тон короткий и технический: «симптом → причина → проверка → действие», без вымышленного incident report, нагрузки или результата rollout.
|
||
- Главная тема: log, metric и trace — разные представления. `traceId` связывает один сценарий в trace и event/log record; metric labels отвечают на агрегирующий вопрос и имеют небольшой фиксированный словарь; event attributes объясняют конкретное событие; evidence-card хранит только допустимый вывод о synthetic модели.
|
||
- Граница: sidecar создаёт ровно пять новых файлов — этот review, один import-safe script и три локальных SVG. Registry, README, `articles.json`, очередь, документация, Git, чужие файлы, staging, commit и push не менялись.
|
||
|
||
## Проход 1 — факты, модель и границы
|
||
|
||
- Историческая граница сверена 31.07.2026 по первичным официальным материалам, доступным к сентябрю 2023: [OpenTelemetry Specification release v1.20.0 от 07.04.2023](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.20.0), [versioned Overview v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/overview.md), [Tracing API v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/api.md), [Metrics Data Model v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/data-model.md) и [Logs Data Model v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/logs/data-model.md). Используются только versioned URLs, а не текущая документация как будто она существовала тогда.
|
||
- Формулировки ограничены источниками. Overview разделяет signals; Tracing API описывает `SpanContext`, `TraceId` и `SpanId`; Metrics Data Model различает events, streams, time series и attributes; Logs Data Model задаёт `LogRecord`, `TraceId`, `SpanId` и attributes. Из этого не сделан ложный вывод о конкретной SDK, collector, exporter, transport, backend, schema maturity, retention, query или dashboards данного проекта.
|
||
- `assembleSyntheticTelemetryScenario()` принимает только fixed synthetic input с точным top-level shape. У valid branch общий `synthetic-trace-2023-09-A` связывает trace и log; event относится к downstream span; metric получает только `service`, `route`, `outcome`. `trace_id`, `span_id`, `request_id`, `user_id`, `order_id`, error text, любые лишние keys в metric labels и любое неизвестное top-level поле отвергаются. Это не универсальная политика для всех backend, а явно названный маленький contract.
|
||
- `runTelemetryFixture()` содержит 19 assertions. Он проверяет correlation trace/log, раздельные span IDs, fixed small labels, отсутствие `trace_id` в labels, event attributes, закрытый input shape, отрицательные ветки mismatch, high-cardinality-like keys, предел модели и rollback. Fixture создаёт records только в памяти и не читает исходники, конфигурацию, Git, часы, сеть, collector, storage или telemetry backend; не создаёт SDK provider, exporter, trace, log или metric и не передаёт данных.
|
||
- Во всех статьях и в коде явно сказано: PASS не доказывает observability, latency, cardinality, trace/log/metric export, поиск, retention, стоимость, production effect, incident, причину ошибки или совместимость SDK. `value: 1` и все identifiers — фиксированные synthetic labels, не измерение и не request identity.
|
||
- Rollback сознательно узкий: он возвращает только snapshot contract draft и ставит `telemetry=not-created-or-deleted`, `productionEffect=not-attempted`. Он не удаляет фактические записи, не выключает instrumentation, sampling, alert, dashboard, collector или backend. Реальный rollback вынесен как отдельное операционное решение с владельцем, средой и проверкой.
|
||
|
||
## Проход 2 — голос, полнота и объём
|
||
|
||
- Первые два абзаца каждого материала называют проблему и цену. Practice показывает несвязанные окна и ошибочный ремонт через identifier в metric labels; mechanism — подмену разных data model общим словом telemetry; field — решение по самой громкой витрине без evidence. Ни один пример не объявлен наблюдением реального сервиса.
|
||
- Practice отвечает на вопрос «как собрать минимальный correlation contract», mechanism — «почему trace ID не является metric label», field — «как пройти diagnostic route, не перепутав симптом и причину». У статей нет дублирующего центрального тезиса: они используют один fixture как общий предмет, но смотрят на него как на контракт, семантику и порядок диагностики.
|
||
- В каждой статье есть: таблица с доступным заголовком; один собственный SVG с осмысленными alt и caption; исполнимый marked synthetic code; упорядоченный route с буквальными словами «симптом → причина → проверка → действие»; отдельные ограничения; rollback; следующий шаг; раздел проверяемых официальных источников. Нет универсальных обещаний и фраз, запрещённых редакционным аудитом.
|
||
- Размер основного текста, посчитанный script без списка источников: practice — 9 949 знаков, mechanism — 10 222 знака, field — 10 197 знаков. Все три текста находятся внутри обязательных 5 000–15 000 знаков и внутри цели 8–11 тыс. `readingMinutes`: 11, 12 и 12 соответственно.
|
||
- Речь соответствует М6: термин не подменяет действие. После `traceId`, `SpanContext`, cardinality, labels и event attributes всегда указано, какое поле проверяется и чего оно не доказывает. Автора 2023 года не выдают за владельца всей платформы: он не приписывает себе реальные dashboards, SLO, incidents, cost data или организационный масштаб.
|
||
|
||
## Проход 3 — визуал, безопасность и выпуск
|
||
|
||
- Три SVG разделяют визуальные задачи: `correlation-map` показывает один key в trace/log и его намеренное отсутствие в metric labels; `cardinality-budget` различает маленький fixed vocabulary и per-request/free-text values; `diagnosis-route` показывает последовательность metric → trace → log/event → evidence и явно перечёркивает подмену correlation новым label. Подписи в каждом файле говорят, что это учебная схема, не production export или измерение.
|
||
- Все SVG самостоятельные: нет `<script>`, `foreignObject`, внешних URL, `data:image`, event handlers, пользовательского ввода или интерактивности. Есть `title`, `desc`, `role="img"`, `aria-labelledby`, контрастные блоки и крупные подписи. XML валиден; safety scan исключает технический `xmlns` из проверки URL.
|
||
- Перед передачей главному агенту выполнены: `node --check web/scripts/upgrade-2023-09.mjs` — PASS; `node web/scripts/upgrade-2023-09.mjs --verify-fixture` — PASS 18/18; `cd web && npm run audit:draft -- scripts/upgrade-2023-09.mjs` — PASS для трёх slug; import-safe comparison CLI/export — PASS, 3 revisions без `date`/`author`; `xmllint --noout` — PASS; SVG safety scan — clean; Sharp-render и ручной просмотр трёх схем на ширине 375 px — PASS.
|
||
- Пакет не интегрирован намеренно. Главный агент должен отдельно провести приёмочное ревью фактов, модели, SVG и затем решать вопрос registry, README, строгого архива, build и Git. Этот sidecar не меняет исходные archive metadata.
|
||
|
||
## Интеграционное ревью главного агента
|
||
|
||
Проведён независимый проход по versioned первоисточникам `v1.20.0`. Release
|
||
зафиксирован 7 апреля 2023; Tracing API определяет `SpanContext`, `TraceId` и
|
||
`SpanId`; metrics data model различает events, streams, time series и
|
||
attributes; logs data model описывает `LogRecord`, `TraceId`, `SpanId` и
|
||
attributes. Поэтому текст сохраняет раздельные вопросы к trace, metric и
|
||
log/event и не делает вывод о конкретной SDK или backend.
|
||
|
||
Model review нашёл, что исходный вход принимал неизвестное top-level поле и
|
||
молча не использовал его. `assembleSyntheticTelemetryScenario()` теперь
|
||
принимает только plain record с точным списком восьми полей; fixture добавил
|
||
отрицательную ветку `unmodeledField`. Так synthetic contract не может выглядеть
|
||
как проверка «контракта плюс неучтённые данные». После исправления fixture
|
||
прошёл `19/19` assertions.
|
||
|
||
Повторный draft audit: 10 005 / 10 249 / 10 228 знаков. Строгий archive audit
|
||
прошёл для трёх slug. Registry содержит 196 уникальных ревизий. Все три SVG
|
||
прошли XML и safety scan, затем были вручную просмотрены после Sharp-render на
|
||
375 px. `npm run build` успешно сгенерировал 374 статические страницы.
|