traceparent и tracestate: полный формат W3C-заголовка

On-call-инженер видит значение traceparent 99-aaaaaaaa-bbbbbbbb-01 в HTTP-заголовке. Валидно ли оно? Использовать его или сгенерировать свежий трейс? Ответ в спеке, и неправильный выбор тихо ломает trace store backend.

Заголовок traceparent по байтам

Спецификация W3C Trace Context (W3C Recommendation с 2020, Level 2 с 2024) определяет один HTTP-заголовок фиксированной ширины. Значение — ровно 55 байт:

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Четыре поля через дефис:

Ширина намеренно фиксирована, чтобы router или sidecar мог парсить заголовок без regex-движка — просто разбей по дефисам и проверь длины байт. Компактная форма означает ~0.04 KB на HTTP-запрос — измеримо, но ничтожно относительно типичных payload’ов.

Trace-id обязан быть равномерно случайным

Спека категорична: trace-id должен генерироваться криптостойким случайным 128-битным значением. Он не должен кодировать timestamp, IP или user-id потому что:

• Downstream-инструменты полагаются на равномерное распределение для решений по sampling (consistent hashing опирается на это).
• Встроенная информация утекает операционные данные.

OTel SDK используют secure random платформы: crypto.getRandomValues в браузерах, /dev/urandom на Linux, java.security.SecureRandom на JVM. Генерация одного 128-битного id — sub-microsecond, никогда не измеримая стоимость. При 128-битной случайности вероятность коллизии среди триллиона трейсов порядка 10⁻¹⁵ — практически ноль.

Уникальность trace-id — фундамент: tracing-backend ключит все span’ы по trace-id, склеивает при запросе, и если два независимых запроса делят id — backend тихо смешает их в один бессмысленный трейс.

Валидация и fallback «нет заголовка»

Когда сервис получает запрос без traceparent или с невалидным (неверная version, all-zero trace-id, malformed hex), receiver обязан сгенерировать совершенно новый trace-id и стартовать свежий трейс. Спека явно определяет этот fallback, чтобы один сбойный caller не каскадно ломал трейсы.

Сбои валидации должны логироваться как атрибут span’а (invalid_traceparent_received=true), чтобы трейс появлялся в backend с маркером, позволяя операторам найти плохого upstream-caller. Production-команды трактуют ненулевую частоту invalid_traceparent span’ов как propagation-регресс.

Пример 99-aaaaaaaa-bbbbbbbb-01: версия 99 неизвестна (текущий max — 00); trace-id и span-id неправильной длины (8 и 8 hex-символов, не 32 и 16). Заголовок невалиден — принимающий сервис стартует свежий трейс.

Компаньон tracestate

Где traceparent — универсальный идентификатор, tracestate несёт vendor-специфичный контекст: какой sampler принял решение, какая canary-версия эмитнула, какие дополнительные id backend хочет.

Формат: comma-separated key=value, до 32 членов, ключ и значение до 256 символов каждый. Спека обязывает vendor’ов пропагировать не менее 512 символов кумулятивного tracestate, даже если они не понимают ключи — это сохраняет end-to-end tracing через разнородные vendor-инструменты.

Правила мутации:

• Vendor может добавить новый ключ (prepend в начало списка).
• Vendor может обновить свой ключ (передвинуть в начало).
• Vendor не должен удалять ключи других vendor’ов.

Заголовок — escape hatch для того, что не вмещается в жёсткий traceparent.

Интерфейс propagator

OpenTelemetry обобщает логику заголовков двумя операциями над объектом Context:

• inject(context, carrier) — пишет нужные заголовки в исходящий запрос.
• extract(carrier) -> context — читает их из входящего запроса.

Carrier’ы pluggable (HTTP-заголовки, gRPC metadata, AMQP properties, обычный dict), propagator’ы pluggable (W3C TraceContext, W3C Baggage, B3 single, B3 multi, Jaeger). Дефолтный OTel composite — TraceContext + Baggage. B3 поддерживается для interop с Zipkin-эрой.

Библиотека делает bit-кодирование, валидацию и логику «если входящего нет — сгенерируй», поэтому прикладной код никогда не трогает сырой hex.