166 lines
15 KiB
Markdown
166 lines
15 KiB
Markdown
# Сентябрь 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 остаётся источником её фактической записи.
|