П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, versioned Overview v1.20.0, Tracing API v1.20.0, Metrics Data Model v1.20.0 и Logs Data Model v1.20.0. Используются только 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 статические страницы.

12 KiB Raw Blame History Unescape Escape