Спецификация W3C Trace Context

Спецификация W3C Trace Context — это стандарт для передачи контекста трассировки через распределённые системы. Она определяет формат заголовков HTTP-запросов, которые позволяют сервисам обмениваться информацией о трассировках, таких как Trace ID и Span ID, в рамках одной или нескольких систем.

Цель стандарта — обеспечить совместимость между инструментами трассировки, такими как OpenTelemetry, Jaeger, Zipkin, и другими.

https://www.w3.org/TR/trace-context/#trace-flags

 

---

Основные понятия W3C Trace Context

1. Trace ID (Идентификатор трассировки)

• Уникальный 16-байтовый (32 символа в 16-ричном формате) идентификатор трассировки.
• Представляет одну полную транзакцию, охватывающую все вызовы между микросервисами.
• Все спаны в одной трассировке имеют одинаковый Trace ID.

2. Span ID (Идентификатор спана)

• Уникальный 8-байтовый (16 символов в 16-ричном формате) идентификатор для каждого спана (операции или блока внутри трассировки).
• Генерируется для каждой новой операции, которую выполняет сервис.

3. Trace Flags (Флаги трассировки)

• Указывает статус трассировки.
• Используется для включения/выключения трассировки.
• 1 байт:
  • 01 — трассировка включена.
  • 00 — трассировка выключена.

4. Version (Версия протокола)

• Определяет версию формата заголовка.
• Текущая версия: 00.

---

Формат заголовка Traceparent

Заголовок traceparent используется для передачи основной информации о трассировке.

Формат:

• {version} — версия формата (2 символа, 00 для текущей версии).
• {trace-id} — уникальный идентификатор трассировки (32 символа).
• {span-id} — уникальный идентификатор спана (16 символов).
• {trace-flags} — флаги трассировки (2 символа, например, 01).

Пример:

• Версия: 00.
• Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736.
• Span ID: 00f067aa0ba902b7.
• Флаги: 01 (включена трассировка).

Формат заголовка Tracestate

Заголовок tracestate используется для передачи дополнительных данных, связанных с трассировкой. Он дополняет traceparent и может содержать информацию о системах, участвующих в трассировке.

Формат:

• Каждая пара ключ=значение передаёт данные конкретного поставщика (например, OpenTelemetry, Jaeger).
• Максимальная длина: 512 символов.
• Пример:
  Default

  tracestate: otel=foo:bar,congo=t61rcWkgMzE

  1 2	tracestate: otel=foo:bar,congo=t61rcWkgMzE

   

Алгоритм работы в распределённой системе

1. Первичный запрос:
   • Первый сервис генерирует traceparent (с уникальными Trace ID и Span ID).
   • Заголовок передаётся в запросе к следующему сервису.
2. Обработка запроса:
   • Сервис принимает traceparent, извлекает Trace ID и создаёт новый Span ID.
   • При необходимости, сервис добавляет или обновляет tracestate.
3. Проксирование:
   • Заголовки traceparent и tracestate передаются в цепочке всех вызовов.
4. Завершение:
   • Каждый сервис записывает свои данные в систему трассировки (например, OpenTelemetry).
   • Данные собираются и визуализируются в инструментах анализа (Jaeger, Zipkin).

---

Пример использования в HTTP-запросе

Клиент отправляет HTTP-запрос:

Сервер обрабатывает запрос, обновляет заголовки:

Преимущества W3C Trace Context

1. Совместимость:
   • Единый стандарт для инструментов трассировки.
   • Простое объединение данных от различных систем.
2. Лёгкость интеграции:
   • Не требует сложной настройки.
   • Поддерживается большинством современных фреймворков и библиотек (например, OpenTelemetry).
3. Расширяемость:
   • Дополнительные данные могут быть переданы через tracestate.

---

Реализация в OpenTelemetry

OpenTelemetry автоматически использует W3C Trace Context для передачи контекста. При этом вы можете:

• Убедиться, что ваш код или инфраструктура правильно проксируют заголовки traceparent и tracestate.
• Включить трассировку в любом поддерживаемом языке, например, Python, Java, Go.

---

Заключение

W3C Trace Context — это стандарт, обеспечивающий удобную и универсальную передачу контекста трассировки. Он состоит из двух ключевых заголовков:

• traceparent — для базовых данных о трассировке.
• tracestate — для расширенных данных.

Его использование позволяет легко интегрировать распределённую трассировку в современные микросервисные архитектуры.