Autumn Docs

ОтелФильтрЭкземпляров ​

Модуль фильтров exemplars (ExemplarFilter): какие измерения могут стать exemplars.

Описание ​

Exemplar — измерение, сохранённое вместе с точкой метрики: значение, время, ID трассировки и спана и атрибуты, которые отбросил фильтр атрибутов потока (формат — в ОтелДанныеМетрики). Фильтр решает, какие измерения предлагаются резервуару exemplars серии, а резервуар — какие из них сохранить (спецификация Metrics SDK, раздел ExemplarFilter).

ФильтрЗначениеOTEL_METRICS_EXEMPLAR_FILTERКакие измерения предлагаются резервуару
ВсегдаВключен()1always_onВсе
ВсегдаВыключен()2always_offНикакие: резервуары exemplars у серий не создаются
ПоТрассировке()3trace_basedЗаписанные в контексте сэмплированного спана

Фильтр один на провайдер метрик и действует на все его инструменты. По умолчанию — ПоТрассировке(). Задают фильтр:

  • методом УстановитьФильтрЭкземпляров ОтелПостроительПровайдераМетрик или третьим параметром конструктора ОтелПровайдерМетрик (Ресурс, Читатели, ФильтрЭкземпляров);
  • переменной окружения OTEL_METRICS_EXEMPLAR_FILTER: построитель провайдера читает её при создании, а УстановитьФильтрЭкземпляров заменяет это значение; конструктор ОтелПровайдерМетрик переменную не читает. Автоконфигурация берёт фильтр из того же параметра (otel.metrics.exemplar.filter). Пустое значение не меняет фильтр, нераспознанное — тоже, о нём пишется предупреждение в лог;
  • в файле конфигурации — значением exemplar_filter секции meter_provider (те же значения).

Фильтр провайдера возвращает его метод ФильтрЭкземпляров(). Выключить exemplars одного потока можно и без фильтра: резервуаром ОтелФабрикаNoopРезервуаров в представлении (ОтелПредставление).

Для ПоТрассировке() спан берётся из контекста измерения: явного параметра Контекст метода записи синхронного инструмента (Добавить, Записать), а без него — из текущего контекста. Спан должен быть валидным и сэмплированным (флаг sampled). У асинхронных инструментов фильтр применяется при сборе наблюдений, к текущему контексту потока, который выполняет сбор; ID трассировки и спана в их exemplars не попадают.

Функции ​

ВсегдаВключен ​

Возвращает фильтр AlwaysOn: резервуару предлагаются все измерения.

Возвращает: Число — 1

ВсегдаВыключен ​

Возвращает фильтр AlwaysOff: exemplars не собираются. Резервуары exemplars у серий не создаются, поэтому накладных расходов на exemplars нет.

Возвращает: Число — 2

ПоТрассировке ​

Возвращает фильтр TraceBased — фильтр по умолчанию: резервуару предлагаются измерения, записанные в контексте сэмплированного спана.

Возвращает: Число — 3

ИзСтроки ​

Возвращает фильтр по значению в формате OTEL_METRICS_EXEMPLAR_FILTER: always_on, always_off или trace_based, без учёта регистра и пробелов по краям. Так построитель провайдера и автоконфигурация разбирают значение переменной окружения; приложение может так же разобрать значение из своих настроек.

ПараметрТипПо умолчаниюОписание
ЗначениеСтрока, Неопределено—Значение фильтра

Возвращает: Число, Неопределено — константа фильтра; Неопределено, если значение не строка или не распознано

Внутренние функции ​

Экспортированы только для вызова из других модулей SDK (в OneScript нет внутренней видимости), приложению вызывать их не нужно:

  • ДолженЗахватить — проверяет по фильтру и контексту измерения, предлагать ли измерение резервуару exemplars; вызывают хранилища потоков метрик при записи измерений и сборе наблюдений.

Пример ​

bsl
// Exemplars для всех измерений, а не только для сэмплированных спанов
Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьРесурс(Ресурс)
    .ЗарегистрироватьЧитатель(Читатель)
    .УстановитьФильтрЭкземпляров(ОтелФильтрЭкземпляров.ВсегдаВключен())
    .Построить();

// Фильтр из настроек приложения в формате OTEL_METRICS_EXEMPLAR_FILTER
Фильтр = ОтелФильтрЭкземпляров.ИзСтроки("always_off"); // ОтелФильтрЭкземпляров.ВсегдаВыключен()
Если Фильтр = Неопределено Тогда
    Фильтр = ОтелФильтрЭкземпляров.ПоТрассировке();
КонецЕсли;
Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьФильтрЭкземпляров(Фильтр)
    .Построить();

См. также ​