Декодер traceparent — W3C Trace Context

Что такое заголовок traceparent?

# The header as it travels on the wire
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate:  rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

# Read the four fields apart
#   version     00
#   trace-id    4bf92f3577b34da6a3ce929d0e0e4736   (16 bytes, whole request)
#   parent-id   00f067aa0ba902b7                   (8 bytes, calling span)
#   trace-flags 01                                 (bit 0 set = sampled)

# Send one yourself
$ curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
       https://example.com/api

Ключевые возможности

Примеры traceparent с разбором

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

version 00 · trace-id 4bf92f3577b34da6a3ce929d0e0e4736 · parent-id 00f067aa0ba902b7 · trace-flags 01 (sampled)

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00

Заголовок корректен · бит sampled сброшен

00-00000000000000000000000000000000-00f067aa0ba902b7-01

Некорректно — trace-id из одних нулей

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

x-datadog-trace-id 11803532876627986230 · _dd.p.tid 4bf92f3577b34da6

Как пользоваться декодером traceparent

1. 1

   Вставьте заголовок traceparent

   Достаточно вставить сырое значение заголовка — например, 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. Декодирование идёт по мере ввода, никаких кнопок нажимать не нужно.

2. 2

   Прочитайте четыре поля по отдельности

   Version, trace-id, parent-id и trace-flags разносятся по своим строкам, у каждой своя кнопка копирования, так что перенести в запрос один только trace ID можно, не выделяя вручную 32 символа.

3. 3

   Проверьте флаги бит за битом

   Байт trace-flags раскладывается на все восемь бит вместе с их масками, поэтому sampled и флаг random-trace-id из Level 2 видны по отдельности, а не спрятаны внутри двухсимвольного значения.

4. 4

   Переведите в формат вашего бэкенда

   Ниже формируются идентификаторы Datadog, AWS X-Ray и оба варианта B3, включая десятичный trace ID из младших 64 бит, который ждёт Datadog, и тег со старшими 64 битами, путешествующий рядом с ним.

5. 5

   Добавьте tracestate и поделитесь результатом

   Вставьте заголовок tracestate, чтобы получить список его элементов с проверкой каждого и счётчиком относительно лимита в 32 элемента, а затем нажмите копирование ссылки, чтобы зафиксировать точное состояние в URL для тикета.

Частые ошибки с traceparent

if (traceFlags === 0x01) { record(); }

if (traceFlags & 0x01) { record(); }

x-datadog-trace-id: 100985939111033328018442752961257817910

x-datadog-trace-id: 11803532876627986230
x-datadog-tags: _dd.p.tid=4bf92f3577b34da6

if (version !== '00') throw new Error('bad traceparent');

if (version !== '00' && header.length >= 55) { /* parse the known prefix */ }

traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Что можно делать декодером traceparent

Понять, почему у трассировки нет спанов

Вставьте входящий заголовок и прочитайте бит sampled. Если он сброшен, трассировку и не собирались записывать, а ответ лежит на стороне вызывающего, а не вашей инструментации, — различие, которое экономит массу времени на аудит собственной конфигурации сэмплирования.

Найти трассировку, которую не находит бэкенд

Если trace ID, скопированный из логов приложения, ничего не возвращает в Datadog, виноват обычно формат. Переведите его здесь, чтобы увидеть десятичный идентификатор из младших 64 бит, которого ждёт API, вместе с тегом из старших 64 бит, обязанным его сопровождать.

Проверить заголовки, которые подставляет шлюз

Прокси и service mesh формируют контекст трассировки на входе. Вставьте то, что пришло на самом деле, и подтвердите длину, строчный шестнадцатеричный регистр и ненулевые идентификаторы, прежде чем считать виноватой следующую систему.

Воспроизвести продакшен-трассировку вручную

Возьмите заголовок из реального запроса и повторите его к стенду, чтобы пройти по той же трассировке. Собрать запрос удобно в конструкторе команд curl и вставить заголовок прямо в него.

Объяснить контекст трассировки команде

Таблицы анатомии полей и значений trace-flags на этой странице — статический справочный материал, на который можно сослаться, а готовые кнопки показывают каждый вариант ошибки без того, чтобы кому-то пришлось ломать сервис ради демонстрации.

Как устроен валидатор W3C Trace Context

Грамматика из четырёх полей

Порядок такой: version, дефис, trace-id, дефис, parent-id, дефис, trace-flags — всё строчными шестнадцатеричными цифрами. В version 2 цифры, в trace-id 32, в parent-id 16, в trace-flags 2: итого 52 шестнадцатеричные цифры плюс 3 дефиса, ровно 55 символов для версии 00. Шестнадцатеричные цифры в верхнем регистре делают заголовок недопустимым, даже если само значение выглядит правильным, а trace-id и parent-id из одних нулей объявлены недопустимыми явно, а не считаются пустыми.

Trace-flags — это битовое поле

Бит 0 (маска 0x01) — sampled: установлен, значит вызывающая сторона могла записать данные трассировки. Бит 1 (маска 0x02), введённый в Level 2, — random-trace-id: если он установлен, как минимум крайние правые 7 байт trace-id должны быть выбраны случайно с равномерным распределением, что позволяет системам ниже по цепочке вести по ним выборку или шардирование. Биты со 2 по 7 зарезервированы, их следует игнорировать при приёме и сбрасывать в исходящих запросах. Поскольку зарезервированные биты могут присутствовать, поле нужно проверять побитовым И — проверка на равенство с 0x01 неверно отчитается о трассировке в выборке, которая несёт ещё и зарезервированный бит.

Совместимость с будущими версиями

Сегодня version равен 00, а ff запрещено, но парсер, отвергающий всё остальное, работает неправильно. Спецификация просит получателей всё же попытаться разобрать заголовок, если версия выше, а длина не меньше известного формата: прочитать поля, которые они распознают, и стерпеть лишние данные в конце, вместо того чтобы начинать трассировку заново. Этот декодер следует правилу: будущая версия разбирается успешно и помечается предупреждением, а не ошибкой.

Лимиты tracestate, которые бьют в продакшене

Не более 32 элементов списка — это жёсткая грамматическая граница: список длиннее делает заголовок недействительным, и получатели его отбрасывают. Каждый ключ не длиннее 256 символов и начинается со строчной буквы или цифры; начиная с Level 2 символ @ — обычный символ ключа, а не разделитель арендатора. Каждое значение состоит из 1–256 печатаемых символов ASCII и никогда не содержит запятой или знака равенства. Повторяющиеся ключи недопустимы, а вот пустые элементы списка спецификация разрешает явно: запятая, оставшаяся после того как посредник удалил запись, по-прежнему даёт корректный заголовок. Отдельно от этого: вендоры должны передавать не менее 512 символов объединённого заголовка; когда ради этого бюджета приходится урезать, первыми должны уходить записи длиннее 128 символов — поэтому данные многословного вендора исчезают раньше, чем у лаконичного.

Лучшие практики работы с Trace Context

Проверяйте флаги побитовым И

Пишите flags & 0x01, а не flags == 0x01. Шесть бит из восьми зарезервированы под будущее, и проверка на равенство начнёт неверно отчитываться о трассировках в выборке в тот момент, когда любой из них появится в реальном трафике.

Считайте идентификатор из одних нулей сломанным конвейером

Это не пустое значение, которое можно стерпеть. Отклоните заголовок и найдите компонент, который не смог инициализировать свой трассировщик или подставляет заглушку.

Когда бит sampled сброшен, смотрите выше по цепочке

Сэмплеры, наследующие решение родителя, распространяют выбор вызывающей стороны. Если трассировки пропадают, сначала определите, какой сервис присылает вам родительский спан с отключённым сэмплированием, и только потом проверяйте собственную конфигурацию.

Держите tracestate коротким

Потолок в 32 элемента — жёсткая грамматическая граница: превысили, и заголовок недействителен. Отдельно от этого гарантируется передача лишь 512 символов объединённого заголовка, а при урезании первыми отбрасываются записи длиннее 128 символов. Всё, что обязано пережить длинную цепочку вызовов, в tracestate не место.

Никогда не записывайте trace ID как число JavaScript

И 128-битный trace ID, и даже 64-битный идентификатор Datadog выходят за Number.MAX_SAFE_INTEGER. Держите их строками и переводите через BigInt, когда нужна арифметика, иначе последние цифры испортятся незаметно.

Часто задаваемые вопросы о декодере traceparent