Пропагация контекста

Пропагация контекста — механизм передачи телеметрических данных (trace ID, baggage) через границы сервисов. SDK поддерживает W3C Trace Context, W3C Baggage и B3 (через отдельный пакет).

Что такое пропагация

При каждом вызове между сервисами необходимо передать информацию о текущей трассировке — иначе спаны разных сервисов не будут связаны в единую трассу. Пропагаторы сериализуют контекст в HTTP-заголовки (Inject) и десериализуют обратно (Extract).

Сервис A (Inject) → HTTP-заголовки → Сервис B (Extract)
   traceparent: 00-4bf92f3577b34da6...
   baggage: userId=alice,env=prod

W3C Trace Context

ОтелW3CПропагатор работает с заголовками traceparent и tracestate по стандарту W3C Trace Context.

Внедрение в исходящий запрос

// Спан уже активен в текущем контексте
Заголовки = Новый Соответствие();
Пропагатор = Новый ОтелW3CПропагатор();
Сеттер = Новый ОтелСеттерТекстовойКарты();

Пропагатор.Внедрить(ОтелКонтекст.Текущий(), Заголовки, Сеттер);
// Заголовки["traceparent"] = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
// Заголовки["tracestate"] = ""

Извлечение из входящего запроса

Пропагатор = Новый ОтелW3CПропагатор();
Геттер = Новый ОтелГеттерТекстовойКарты();

НовыйКонтекст = Пропагатор.Извлечь(ОтелКонтекст.Текущий(), ВходящиеЗаголовки, Геттер);

// Создание дочернего спана в извлечённом контексте
Спан = Трассировщик.НачатьДочернийСпан("обработка", НовыйКонтекст, ОтелВидСпана.Сервер());

W3C Baggage

ОтелW3CBaggageПропагатор передаёт произвольные данные в заголовке baggage по стандарту W3C Baggage.

// Создание baggage
Baggage = Новый ОтелBaggage();
Baggage.УстановитьЭлемент("userId", "alice");
Baggage.УстановитьЭлемент("env", "production");

// Помещение baggage в контекст
КонтекстСBaggage = ОтелКонтекст.Текущий().УстановитьBaggage(Baggage);

// Внедрение в заголовки
Заголовки = Новый Соответствие();
Пропагатор = Новый ОтелW3CBaggageПропагатор();
Сеттер = Новый ОтелСеттерТекстовойКарты();
Пропагатор.Внедрить(КонтекстСBaggage, Заголовки, Сеттер);
// Заголовки["baggage"] = "userId=alice,env=production"

// Извлечение на стороне получателя
Геттер = Новый ОтелГеттерТекстовойКарты();
НовыйКонтекст = Пропагатор.Извлечь(ОтелКонтекст.Текущий(), ВходящиеЗаголовки, Геттер);
ПолученныйBaggage = НовыйКонтекст.ПолучитьBaggage();

Композитный пропагатор

ОтелКомпозитныйПропагатор объединяет несколько пропагаторов. Inject и Extract вызываются для каждого из них последовательно.

Пропагатор = Новый ОтелКомпозитныйПропагатор();
Пропагатор.ДобавитьПропагатор(Новый ОтелW3CПропагатор());
Пропагатор.ДобавитьПропагатор(Новый ОтелW3CBaggageПропагатор());

// Использование через глобальный SDK
ОтелГлобальный.УстановитьПропагаторы(Пропагатор);

// Внедрение всех форматов сразу
Заголовки = Новый Соответствие();
Пропагаторы = ОтелГлобальный.ПолучитьПропагаторы();
Пропагаторы.Внедрить(ОтелКонтекст.Текущий(), Заголовки);
// traceparent + tracestate + baggage — все в одних заголовках

Геттер и сеттер текстовой карты

ОтелГеттерТекстовойКарты и ОтелСеттерТекстовойКарты — адаптеры для работы с Соответствие:

// Сеттер — записывает заголовок в соответствие
Сеттер = Новый ОтелСеттерТекстовойКарты();

// Геттер — читает заголовок из соответствия (регистронезависимо)
Геттер = Новый ОтелГеттерТекстовойКарты();

// Можно реализовать собственный геттер/сеттер для
// нестандартных структур данных (например, заголовки HTTP-запроса)

Пропагаторы по умолчанию

При автоконфигурации ОтелАвтоконфигурация.Инициализировать() автоматически регистрирует пропагаторы, заданные в OTEL_PROPAGATORS (по умолчанию: tracecontext,baggage).

// После автоконфигурации — глобальные пропагаторы уже настроены
Сдк = ОтелАвтоконфигурация.Инициализировать();

// Inject/Extract через глобальный доступ
Пропагаторы = ОтелГлобальный.ПолучитьПропагаторы();
Пропагаторы.Внедрить(ОтелКонтекст.Текущий(), Заголовки);

B3 пропагатор (отдельный пакет)

Согласно спецификации Propagators Distribution, B3 и Jaeger пропагаторы поставляются отдельными пакетами.

Для поддержки B3 установите пакет opentelemetry-propagator-b3:

opm install opentelemetry-propagator-b3

После установки включите B3 через переменную окружения:

# B3 Single Header
export OTEL_PROPAGATORS=tracecontext,baggage,b3

# B3 Multi Header
export OTEL_PROPAGATORS=tracecontext,baggage,b3multi

B3 Single Header использует заголовок b3, B3 Multi Header — отдельные заголовки X-B3-TraceId, X-B3-SpanId, X-B3-Sampled.

Настройка через переменные окружения

Переменная	По умолчанию	Описание
OTEL_PROPAGATORS	tracecontext,baggage	Список пропагаторов через запятую

Поддерживаемые значения:

Значение	Пропагатор	Заголовки
tracecontext	ОтелW3CПропагатор	traceparent, tracestate
baggage	ОтелW3CBaggageПропагатор	baggage
b3	B3 Single (пакет opentelemetry-propagator-b3)	b3
b3multi	B3 Multi (пакет opentelemetry-propagator-b3)	X-B3-TraceId, X-B3-SpanId, …
none	—	Отключить все пропагаторы

Смотрите также

• Автоконфигурация — настройка OTEL_PROPAGATORS
• Трассировка — создание спанов и контекст
• API: ОтелW3CПропагатор
• API: ОтелКомпозитныйПропагатор