revise September 2020 tracing articles

editorial/reviews/2020-09-draft.md

@@ -0,0 +1,165 @@
+# Сентябрь 2020 — тройное ревью автономного пакета P31 «Трассировка запроса»
+
+Статус: **принят независимым редактором в выпусковой набор**. В revision нет
+<code>date</code> и <code>author</code>; слой публикации сохраняет их из
+базового архива. Автономный авторский пакет не менял registry,
+<code>articles.json</code>, стандарт, очередь, package configuration или Git.
+
+Проверенные revision:
+
+- <code>editorial-2020-09-practice-tracing-basics</code>;
+- <code>editorial-2020-09-mechanism-tracing-basics</code>;
+- <code>editorial-2020-09-field-tracing-basics</code>.
+
+Модуль экспортирует ровно три revision. При <code>--print-revisions</code>
+stdout содержит только JSON. При <code>--verify-fixture</code> запускается
+только in-memory модель одного synthetic trace; она не открывает сеть, не
+читает production-журнал и не вызывает collector.
+
+## Проход 1. Факты, историческая рамка и механизм — пройдено
+
+| Утверждение или решение | Первичный / официальный источник | Зафиксированная граница |
+| --- | --- | --- |
+| <code>Trace Context Level 1</code> — W3C Recommendation от 06 февраля 2020 года, а не черновик сентября 2020 | [W3C Trace Context Level 1, 2020-02-06](https://www.w3.org/TR/2020/REC-trace-context-1-20200206/) | Тексты называют готовым именно переносимый format <code>traceparent</code>, а не «готовую трассировочную платформу». |
+| Для version <code>00</code> <code>traceparent</code> несёт version, 32-hex trace-id, 16-hex parent-id и trace-flags; нулевые ID невалидны | [W3C Trace Context, sections 3.2–3.2.2](https://www.w3.org/TR/2020/REC-trace-context-1-20200206/) | Учебный parser принимает только <code>00</code>, lowercase hex, ненулевые ID и <code>00</code>/<code>01</code> flags; он не притворяется generic parser-ом будущих версий. |
+| В 2020 OpenTelemetry-specification ещё была до 1.0; tag <code>v0.5.0</code> датирован 02 июня 2020 | [OpenTelemetry Specification v0.5.0 changelog](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.5.0/CHANGELOG.md) | Пакет не приписывает сентябрю 2020 стабильный collector, auto-instrumentation, service map или version-independent SDK. |
+| Официальная документация относит стабильность Trace API к началу 2021 года | [OpenTelemetry Libraries](https://opentelemetry.io/docs/concepts/instrumentation/libraries/) | Это редакционная историческая сверка: текст сентября 2020 остаётся transport-neutral учебным разбором, а не ретроспективной инструкцией по современной экосистеме. |
+
+Техническая модель повторно сверена после авторского прохода:
+
+- один synthetic trace-id связывает ровно пять span;
+- <code>catalog.lookup</code> получает gateway как parent, а
+  <code>inventory.fetch</code> — catalog;
+- duration считается только как <code>endMs - startMs</code>;
+- child intervals полностью лежат внутри parent intervals в пределах fixture;
+- pricing и inventory перекрываются, поэтому их duration не суммируются;
+- выбранный fixture critical path —
+  <code>gateway.handle → catalog.lookup → inventory.fetch → inventory.adapter</code>;
+- exclusive segments выбранной цепочки равны <code>40 + 30 + 100 + 70 = 240 ms</code>, то есть root duration;
+- invalid all-zero trace-id и зарезервированный <code>09</code> flags отвергаются.
+
+Выполнен <code>--verify-fixture</code>. Реальный результат содержит восемь
+истинных assertions: round-trip <code>traceparent</code>, получение текущего
+parent child-операцией, общий trace-id, положительные intervals, ожидаемый
+critical path, совпадение exclusive суммы с root и два негативных случая.
+Fixture использует только synthetic IDs, services, интервалы и header:
+<code>training-gateway</code>, <code>training-catalog</code>,
+<code>training-inventory</code> и
+<code>00-4bf92f3577b34da6a3ce929d0e0e4736-a111111111111111-01</code>.
+
+Вердикт прохода: **пройден**. Поправлена дополнительная техническая граница:
+version <code>00</code> fixture больше не принимает произвольный двухсимвольный
+flags byte; <code>01</code> остаётся примером sampled bit, но не policy,
+которой должен доверять публичный вход.
+
+## Проход 2. Редактура, голос М3 и плотность — пройдено
+
+| Revision | Проблема и цена в первых двух абзацах | Главный вопрос | Голос и следующий шаг |
+| --- | --- | --- | --- |
+| Практика | Логи есть, но 240 ms не разложены; правка timeout/retry/базы по догадке увеличивает стоимость следующего сбоя | Как сохранить один context и увидеть один учебный waterfall | М3 связывает границы gateway, catalog и inventory; сначала проверяет carrier и fixture, затем предлагает один transport test. |
+| Механизм | Разные trace-id или потерянный parent создают ложную причинность и неправильного «виновника» | Что реально несут trace-id, span-id, parent-id, flags и duration | М3 описывает W3C contract и прямую ответственность transport boundary, не выдавая carrier за бизнес-API. |
+| Полевой разбор | Самый заметный span провоцирует оптимизацию не той ветви | Как отделить inclusive duration от critical path одной истории | М3 разбирает controlled fixture, называет overlap и выбирает одну следующую проверку вместо диагноза production-системы. |
+
+- Draft gate после финальной технической правки измерил основной текст без
+  источников: практика — **10 269** знаков, механизм — **11 727**, полевой
+  разбор — **9 702**. Все три текста попадают в диапазон 5 000–15 000.
+- В каждом revision есть 8–9 смысловых разделов, две таблицы с
+  <code>caption</code>/<code>thead</code>, две figure с осмысленными
+  <code>alt</code>/<code>figcaption</code>, два code/example блока,
+  нумерованный маршрут и три официальные или первичные ссылки.
+- Структура держит краткую последовательность «симптом → причина → проверка
+  → действие». Примеры не подменяют проверку общими словами о важности
+  наблюдаемости.
+- В текст не внесены современные обещания: нет production latency, реального
+  trace или URL, сервиса карт, стабильного tracing platform, готовой
+  collector-конфигурации, автоматического instrumentor-а или наблюдаемого
+  инцидента пользователя.
+- Используется исторически подходящий словарь М3: trace context, span,
+  transport boundary, fixture, overlap и clock skew раскрываются рядом с
+  конкретным действием. Автор учится связать события между сервисами, но не
+  пишет от лица владельца зрелой платформы.
+
+Вердикт прохода: **пройден**. Тексты сохраняют техническую плотность и
+соответствуют сентябрю 2020 года без анахронизмов.
+
+## Проход 3. Визуал, доступность и выпуск автономного пакета — пройдено в заданных границах
+
+- <code>tracing-span-waterfall-2020.svg</code> показывает пять intervals на
+  шкале 0–240 ms, overlap pricing/inventory и выделенную позднюю цепочку.
+- <code>tracing-context-propagation-2020.svg</code> показывает отдельные
+  шаги inject/extract, неизменность trace-id и смену текущего span-id без
+  имитации сетевого трафика.
+- <code>tracing-critical-path-2020.svg</code> показывает разницу inclusive и
+  exclusive duration, параллельный pricing и расчёт 240 ms.
+- У каждого SVG есть <code>title</code>, <code>desc</code>,
+  <code>role="img"</code>, вертикальный viewBox, контрастные карточки и
+  короткие подписи. Нет JavaScript, <code>foreignObject</code>, внешних URL,
+  data URI или пользовательских данных.
+- Все три SVG отрендерены Sharp при ширине **375 px** и просмотрены вручную.
+  Текст, bars и нижние карточки читаемы; обрезания, наложения и горизонтальный
+  overflow внутри SVG не обнаружены. Waterfall оставлен вертикальным именно
+  для этой ширины.
+
+### Фактические команды и результаты
+
+<pre><code>cd web
+node --check scripts/upgrade-2020-09.mjs
+npm run audit:draft -- scripts/upgrade-2020-09.mjs
+node scripts/upgrade-2020-09.mjs --verify-fixture
+xmllint --noout \
+  public/assets/editorial/2020/tracing-span-waterfall-2020.svg \
+  public/assets/editorial/2020/tracing-context-propagation-2020.svg \
+  public/assets/editorial/2020/tracing-critical-path-2020.svg</code></pre>
+
+| Проверка | Реальный результат |
+| --- | --- |
+| <code>node --check</code> | код завершения 0 |
+| Draft audit | PASS: 10 269 / 11 727 / 9 702 знаков тела |
+| In-memory fixture | 8 assertions вернули <code>true</code>; root duration и selected exclusive path равны 240 ms |
+| XML | все три SVG валидны, код завершения 0 |
+| 375 px visual preflight | выполнен через локальный Sharp-render и ручной просмотр; SVG читаемы, без clipping/overflow |
+| Scope/self-review | revision не переопределяет <code>date</code>/<code>author</code>; в работе изменены только пять разрешённых файлов P31 |
+
+Не запускались browser-review опубликенной страницы, реальный HTTP,
+reverse proxy, browser instrumentation, OpenTelemetry SDK/collector,
+exporter, clock synchronization, CI, production build, deployment или
+assistive-technology проверка. Наличие осмысленных alt-текстов и подписей не
+заменяет проверку скринридером.
+
+## Итог
+
+Статус: **тройное ревью пройдено, пакет P31 принят к отдельной публикации**.
+
+После трёх проходов зафиксированы три существенные границы качества:
+
+1. W3C Trace Context Recommendation 2020 отделена от незрелости ранней
+   OpenTelemetry-экосистемы; статья не обещает современный platform-level
+   результат.
+2. Fixture проверяет не только красивую схему: он связывает trace context,
+   parent/child relation, duration и exclusive critical path в одном
+   синтетическом запросе.
+3. SVG переделаны как крупные вертикальные схемы и отдельно проверены на
+   ширине 375 px; публикационный слой, архив и чужие незакоммиченные файлы
+   намеренно не затронуты.
+
+## Независимая интеграционная приёмка
+
+Основной редактор 31 июля 2026 года подключил три revision к
+<code>web/data/editorial-revisions.mjs</code>, не меняя базовый
+<code>articles.json</code>, даты или автора архивных записей. В registry стало
+88 revision. Отдельно выполнены:
+
+| Проверка после интеграции | Реальный результат |
+| --- | --- |
+| Строгий audit трёх slug | PASS: 10 269 / 11 727 / 9 702 знаков; у каждой статьи есть figures, tables и code examples |
+| Production build | PASS: Next.js собрал 374 статические страницы |
+| Независимый mobile visual review | PASS: основной редактор повторно просмотрел три SVG после Sharp-рендера в 375 px; clipping, overlap и overflow не обнаружены |
+
+W3C Recommendation от 6 февраля 2020 года сверена независимо по первичному
+тексту: она действительно описывает перенос контекста через
+<code>traceparent</code>, но не обещает готовую tracing-платформу. В отчёте не
+утверждается запуск реального HTTP, proxy, OpenTelemetry SDK/collector,
+browser или assistive technology.
+
+Выпусковой вердикт: **ACCEPT**. Commit и push выполняются отдельной
+публикационной операцией; Git остаётся источником её фактической записи.