ОтелСэмплер
Модуль — встроенные сэмплеры и решения сэмплера.
Описание
Сэмплер решает при создании каждого спана, записывается ли спан и экспортируется ли он (раздел Sampling спецификации Trace SDK). Модуль создаёт встроенные сэмплеры — AlwaysOn, AlwaysOff, TraceIdRatioBased, ParentBased и AlwaysRecord — и содержит константы решений. Сэмплер — объект с методами ИнтерфейсСэмплер: ДолженСэмплировать (ShouldSample) и Описание (GetDescription). Свой сэмплер реализует тот же интерфейс.
Сэмплер задаётся провайдеру трассировки при создании: методом УстановитьСэмплерпостроителя провайдера, параметром конструктора провайдера, переменными окружения OTEL_TRACES_SAMPLER и OTEL_TRACES_SAMPLER_ARG (автоконфигурация) или секцией tracer_provider.sampler файла конфигурации. Сэмплер по умолчанию — ParentBased(root=AlwaysOn): корневые спаны сэмплируются все, дочерние наследуют решение родителя.
Сэмплеры комбинируются: НаОсновеРодителя и ВсегдаЗаписывать принимают другие сэмплеры, встроенные или свои. Встроенные сэмплеры после создания не изменяются и безопасны при вызове из нескольких потоков.
Аналог Java SDK: Sampler и его статические фабрики (Sampler.alwaysOn(), Sampler.traceIdRatioBased(ratio), Sampler.parentBasedBuilder(root)).
Встроенные сэмплеры
ВсегдаВключен
Возвращает сэмплер AlwaysOn: решение РешениеЗаписатьИЭкспортировать для любого спана. Функция возвращает один и тот же объект.
Возвращает: ОтелСэмплерВсегдаВключен — сэмплер с описанием AlwaysOnSampler
ВсегдаВыключен
Возвращает сэмплер AlwaysOff: решение РешениеОтбросить для любого спана. Функция возвращает один и тот же объект.
Возвращает: ОтелСэмплерВсегдаВыключен — сэмплер с описанием AlwaysOffSampler
ПоДолеТрассировок
Создаёт сэмплер TraceIdRatioBased: сэмплирует заданную долю трассировок по их TraceId. Решение — детерминированная функция TraceId: значение случайности R — правые 7 байт TraceId (случайные по W3C Trace Context Level 2), трассировка сэмплируется, если R >= (1 - Доля) * 2^56. Поэтому все спаны трассировки получают одно решение, а сэмплер с большей долей сэмплирует все трассировки сэмплера с меньшей. Флаг sampled родителя сэмплер не учитывает: чтобы дочерние спаны наследовали решение родителя, используйте сэмплер корневым в НаОсновеРодителя.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Доля | Число | — | Доля трассировок для сэмплирования, от 0.0 до 1.0; 1.0 и больше — все трассировки, 0 и меньше — ни одной |
Возвращает: ОтелСэмплерПоДолеТрассировок — сэмплер с описанием TraceIdRatioBased{ДОЛЯ}. Доля выводится с шестью знаками после точки (TraceIdRatioBased{0.250000}), а если у неё больше значащих знаков — со всеми (TraceIdRatioBased{0.1234561}): сэмплеры с разными долями различаются по описанию
НаОсновеРодителя
Создаёт сэмплер ParentBased: решение для корневого спана принимает корневой сэмплер, для дочернего — делегат, выбранный по родителю.
| Родитель | Удалённый (Удаленный()) | Сэмплирован (флаг sampled) | Решает |
|---|---|---|---|
| нет | — | — | Корневой |
| есть | да | да | УдаленныйРодительСэмплирован |
| есть | да | нет | УдаленныйРодительНеСэмплирован |
| есть | нет | да | ЛокальныйРодительСэмплирован |
| есть | нет | нет | ЛокальныйРодительНеСэмплирован |
Родитель с невалидным SpanContext (например, ОтелСпаны.Невалидный) считается отсутствующим. Удалённый родитель — контекст, извлечённый пропагатором из входящего запроса.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Корневой | ИнтерфейсСэмплер | — | Сэмплер корневых спанов (root) |
УдаленныйРодительСэмплирован | ИнтерфейсСэмплер | ВсегдаВключен() | Удалённый родитель сэмплирован (remoteParentSampled) |
УдаленныйРодительНеСэмплирован | ИнтерфейсСэмплер | ВсегдаВыключен() | Удалённый родитель не сэмплирован (remoteParentNotSampled) |
ЛокальныйРодительСэмплирован | ИнтерфейсСэмплер | ВсегдаВключен() | Локальный родитель сэмплирован (localParentSampled) |
ЛокальныйРодительНеСэмплирован | ИнтерфейсСэмплер | ВсегдаВыключен() | Локальный родитель не сэмплирован (localParentNotSampled) |
Возвращает: ОтелСэмплерНаОсновеРодителя — сэмплер с описанием ParentBased{root:...,remoteParentSampled:...,remoteParentNotSampled:...,localParentSampled:...,localParentNotSampled:...} из описаний корневого сэмплера и делегатов
ВсегдаЗаписывать
Создаёт сэмплер AlwaysRecord: решение обёрнутого сэмплера РешениеОтбросить заменяется на РешениеЗаписать, решения РешениеЗаписать и РешениеЗаписатьИЭкспортировать, атрибуты и TraceState обёрнутого сэмплера не меняются. Процессоры получают все спаны — например, чтобы считать метрики по всем спанам, — а экспортер получает только спаны, сэмплированные обёрнутым сэмплером.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Корневой | ИнтерфейсСэмплер | — | Обёрнутый сэмплер (root) |
Возвращает: ОтелСэмплерВсегдаЗаписывать — сэмплер с описанием AlwaysRecord{ОПИСАНИЕ_ОБЁРНУТОГО}
Решения сэмплера
РешениеЗаписатьИЭкспортировать
Решение RECORD_AND_SAMPLE: спан записывается, флаг sampled устанавливается, спан экспортируется.
Возвращает: Число — 2
РешениеЗаписать
Решение RECORD_ONLY: спан записывается и передаётся процессорам, но флаг sampled не устанавливается и экспортер спан не получает.
Возвращает: Число — 1
РешениеОтбросить
Решение DROP: спан не записывается, возвращается незаписывающий спан.
Возвращает: Число — 0
Служебные функции
Результат
Возвращает результат сэмплирования с решением, без атрибутов и не меняющий TraceState: спан получает TraceState родителя. Результаты трёх решений создаются один раз, поэтому сэмплер может возвращать их, не создавая объект на каждый спан. Встроенные сэмплеры возвращают эти результаты.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Решение | Число | — | РешениеОтбросить(), РешениеЗаписать() или РешениеЗаписатьИЭкспортировать() |
Возвращает: ОтелРезультатСэмплирования — неизменяемый результат
КонтекстСпанаРодителя
Возвращает SpanContext родителя создаваемого спана из контекста, который получает сэмплер в ДолженСэмплировать.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Контекст | ФиксированноеСоответствие, Соответствие | — | Контекст (Context), переданный сэмплеру |
Возвращает: ОтелКонтекстСпана, Неопределено — контекст спана родителя; Неопределено, если спан корневой: в контексте нет спана или его SpanContext невалиден
Пример
// Сэмплировать 10% новых трассировок, дочерние спаны наследуют решение родителя
Провайдер = Новый ОтелПостроительПровайдераТрассировки()
.УстановитьСэмплер(ОтелСэмплер.НаОсновеРодителя(ОтелСэмплер.ПоДолеТрассировок(0.1)))
.Построить();
// Решение удалённого родителя (входящего запроса) не учитывать: к таким трассировкам тоже
// применять долю 10%
ПоДоле = ОтелСэмплер.ПоДолеТрассировок(0.1);
Провайдер = Новый ОтелПостроительПровайдераТрассировки()
.УстановитьСэмплер(ОтелСэмплер.НаОсновеРодителя(ПоДоле, ПоДоле, ПоДоле))
.Построить();
// Процессоры получают все спаны, экспортируется 10% трассировок
Провайдер = Новый ОтелПостроительПровайдераТрассировки()
.УстановитьСэмплер(ОтелСэмплер.ВсегдаЗаписывать(ОтелСэмплер.НаОсновеРодителя(ПоДоле)))
.Построить();
Сообщить(Провайдер.Сэмплер().Описание());
// AlwaysRecord{ParentBased{root:TraceIdRatioBased{0.100000},remoteParentSampled:AlwaysOnSampler,...}}