Публичный интерфейс библиотеки opentelemetry-propagator-b3

Классы

• ОтелB3Пропагатор

Модули

• ОтелФорматB3

---

ОтелB3Пропагатор

Пропагатор контекста трассировки B3 (Zipkin).

Описание

Реализует внедрение и извлечение контекста трассировки через HTTP-заголовки в форматах B3 multi-header и single-header.

Multi-header формат:

• X-B3-TraceId — идентификатор трассировки (32 символа hex)
• X-B3-SpanId — идентификатор спана (16 символов hex)
• X-B3-Sampled — флаг сэмплирования ("1" / "0")
• X-B3-Flags — флаг отладки ("1" = debug)

Single-header формат:

• b3: {traceId}-{spanId}-{sampling}-{parentSpanId}
• Для отладочного режима: b3: {traceId}-{spanId}-d
• Deny sampling: b3: 0

При извлечении контекста оба формата поддерживаются одновременно: single-header (b3) имеет приоритет над multi-header (X-B3-*).

Флаг отладки B3 (X-B3-Flags: 1 / b3: ...d) сохраняется в контексте через специальный ключ, доступный через метод КлючОтладки().

Конструктор

Новый ОтелB3Пропагатор(Формат)

Параметр	Тип	По умолчанию	Описание
Формат	Строка	ОтелФорматB3.Одиночный()	Формат внедрения заголовков: ОтелФорматB3.Мульти() или ОтелФорматB3.Одиночный()

Методы

Внедрить

Внедряет контекст трассировки в HTTP-заголовки носителя. Формат заголовков определяется параметром конструктора. Если контекст не содержит валидного спана — ничего не делает.

Параметр	Тип	По умолчанию	Описание
Контекст	Соответствие	—	OTel Context
Носитель	Произвольный	—	Носитель заголовков
Сеттер	ОтелСеттерТекстовойКарты	Стандартный сеттер	Объект для записи в носитель (по умолчанию для Соответствие)

Извлечь

Извлекает контекст трассировки из HTTP-заголовков носителя. Поддерживает оба формата: single-header имеет приоритет. При невалидных идентификаторах (неверная длина, all-zeros) возвращает исходный контекст.

Параметр	Тип	По умолчанию	Описание
Контекст	Соответствие	—	Входной OTel Context
Носитель	Произвольный	—	Носитель заголовков
Геттер	ОтелГеттерТекстовойКарты	Стандартный геттер	Объект для чтения из носителя (по умолчанию для Соответствие)

Возвращает: Соответствие — новый контекст с извлечённым SpanContext (или входной контекст при ошибке)

Поля

Возвращает список HTTP-заголовков, используемых пропагатором. Набор зависит от выбранного формата инъекции.

Возвращает: Массив из Строка

• Для single: ["b3"]
• Для multi: ["X-B3-TraceId", "X-B3-SpanId", "X-B3-Sampled", "X-B3-Flags"]

КлючОтладки

Возвращает ключ контекста для хранения debug-флага B3. Аналог B3Propagator.DEBUG_CONTEXT_KEY из Java SDK.

Возвращает: ОтелКлючКонтекста — ключ для доступа к debug-флагу в контексте

Пример

#Использовать opentelemetry
#Использовать opentelemetry-propagator-b3

// Single-header (по умолчанию)
Пропагатор = Новый ОтелB3Пропагатор();

// Multi-header
Пропагатор = Новый ОтелB3Пропагатор(ОтелФорматB3.Мульти());

// Внедрить в исходящий запрос
Заголовки = Новый Соответствие();
Пропагатор.Внедрить(ОтелКонтекст.Текущий(), Заголовки);
// Single: { "b3": "4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-1" }
// Multi: { "X-B3-TraceId": "4bf9...", "X-B3-SpanId": "00f0...", "X-B3-Sampled": "1" }

// Извлечь из входящего запроса
ВходящиеЗаголовки = Новый Соответствие();
ВходящиеЗаголовки.Вставить("b3", "4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-1");
НовыйКонтекст = Пропагатор.Извлечь(Новый Соответствие(), ВходящиеЗаголовки);

// Проверить debug-флаг
ЭтоОтладка = НовыйКонтекст.Получить(Пропагатор.КлючОтладки());

// Использовать совместно с W3C пропагатором через композитный
СписокПропагаторов = Новый Массив();
СписокПропагаторов.Добавить(Новый ОтелW3CПропагатор());
СписокПропагаторов.Добавить(Новый ОтелB3Пропагатор());
КомпозитныйПропагатор = Новый ОтелКомпозитныйПропагатор(СписокПропагаторов);

---

ОтелФорматB3

Модуль констант формата инъекции B3 пропагатора.

Описание

Определяет формат HTTP-заголовков при внедрении контекста трассировки через ОтелB3Пропагатор.

Используется при создании пропагатора для явного указания формата:

Пропагатор = Новый ОтелB3Пропагатор(ОтелФорматB3.Мульти());

Методы модуля

Мульти

Возвращает идентификатор multi-header формата.

В этом формате контекст трассировки передаётся через несколько заголовков:

• X-B3-TraceId — идентификатор трассировки
• X-B3-SpanId — идентификатор спана
• X-B3-Sampled — флаг сэмплирования ("1" / "0")
• X-B3-Flags — флаг отладки ("1" = debug trace)

Возвращает: Строка — идентификатор формата "multi"

Одиночный

Возвращает идентификатор single-header формата.

В этом формате контекст трассировки передаётся в одном заголовке b3:

• Формат: {traceId}-{spanId}-{sampling}[-{parentSpanId}]
• Пример: 4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-1
• Отладочный режим: ...-d вместо ...-1

Возвращает: Строка — идентификатор формата "single"

Пример

#Использовать opentelemetry-propagator-b3

// Создать пропагатор с single-header форматом (по умолчанию)
Пропагатор = Новый ОтелB3Пропагатор(ОтелФорматB3.Одиночный());
// b3: 4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-1

// Создать пропагатор с multi-header форматом
Пропагатор = Новый ОтелB3Пропагатор(ОтелФорматB3.Мульти());
// X-B3-TraceId: 4bf92f3577b34da6a3ce929d0e0e4736
// X-B3-SpanId: 00f067aa0ba902b7
// X-B3-Sampled: 1

// Проверить формат
Формат = ОтелФорматB3.Мульти(); // "multi"
Формат = ОтелФорматB3.Одиночный(); // "single"