Autumn Docs

ОтелСелекторВременнойАгрегации ​

Модуль селекторов временной агрегации (AggregationTemporalitySelector) для экспортёра метрик.

Описание ​

Селектор задаёт временную агрегацию (ОтелВременнаяАгрегация) по типу инструмента. Его передают в конструктор ОтелЭкспортерМетрик параметром СелекторВременнойАгрегации; без него экспортёр использует ВсегдаКумулятивная().

Селектор — объект с функцией Применить(ТипИнструмента), которая возвращает ОтелВременнаяАгрегация.Кумулятивная() или ОтелВременнаяАгрегация.Дельта(). Функции модуля возвращают готовые селекторы; свой селектор — любой объект с такой функцией.

Как применяется селектор:

  • Периодический читатель запрашивает у экспортёра (ПолучитьВременнуюАгрегацию) временную агрегацию для вида инструмента каждого потока, собирает поток с ней и записывает её в данные метрики (ВременнаяАгрегация()ОтелДанныеМетрики). Значение, отличное от Дельта(), читатель считает кумулятивной агрегацией.
  • OTLP-экспортёр передаёт временную агрегацию данных в OTLP, а для данных без неё (от продюсеров метрик) выбирает её селектором по типу метрики: монотонная сумма — counter, немонотонная — up_down_counter, гистограмма — histogram, экспоненциальная гистограмма — exponentialHistogram.
  • Prometheus-читатель селектор не использует: его данные всегда кумулятивные.

С кумулятивной агрегацией точки содержат значения, накопленные с создания потока, с дельта-агрегацией — значения за время с прошлого сбора (у асинхронной суммы — разницу с наблюдением прошлого сбора). Дельта-поток синхронного инструмента не хранит серии между сборами: серия без измерений за интервал не выводится. У датчиков временной агрегации в OTLP нет, но от неё зависит сбор синхронного датчика: с дельтой выводятся только серии, записанные после прошлого сбора.

Типы инструментов ​

Тип инструментаИнструментВсегдаКумулятивнаяПредпочтительноДельтаНизкоеПотреблениеПамяти
counterОтелСчетчиккумулятивнаядельтадельта
up_down_counterОтелРеверсивныйСчетчиккумулятивнаякумулятивнаякумулятивная
histogramОтелГистограммакумулятивнаядельтадельта
gaugeОтелДатчиккумулятивнаядельтакумулятивная
observable_counterОтелНаблюдаемыйСчетчиккумулятивнаядельтакумулятивная
observable_up_down_counterОтелНаблюдаемыйРеверсивныйСчетчиккумулятивнаякумулятивнаякумулятивная
observable_gaugeОтелНаблюдаемыйДатчиккумулятивнаядельтакумулятивная

Другой тип (например, exponentialHistogram у данных продюсера) ПредпочтительноДельта относит к дельте, а НизкоеПотреблениеПамяти — к кумулятивной агрегации.

Настройка ​

Автоконфигурация (переменная окружения) и файл конфигурации (temporality_preference экспортёра otlp_http или otlp_grpc) выбирают селектор OTLP-экспортёра метрик по предпочтению временной агрегации:

СелекторOTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCEtemporality_preference
ВсегдаКумулятивнаяcumulative (по умолчанию)cumulative (по умолчанию)
ПредпочтительноДельтаdeltadelta
НизкоеПотреблениеПамятиlowmemorylow_memory

Значения читаются без учёта регистра. В переменной окружения подчёркивания не учитываются (подходит и low_memory). Нераспознанное значение даёт ВсегдаКумулятивная, автоконфигурация пишет о нём предупреждение в лог.

Функции ​

ВсегдаКумулятивная ​

Возвращает селектор для предпочтения cumulative: кумулятивная агрегация для всех типов инструментов. Селектор по умолчанию.

Возвращает: УниФункция — селектор: Применить(ТипИнструмента) возвращает ОтелВременнаяАгрегация.Кумулятивная()

ПредпочтительноДельта ​

Возвращает селектор для предпочтения delta (спецификация OTLP Metric Exporter, переменная OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE): кумулятивная агрегация для up_down_counter и observable_up_down_counter, дельта — для остальных типов. Спецификация задаёт дельту для счётчиков (синхронного и асинхронного) и гистограммы, а про датчики не говорит; SDK, как Java SDK, выбирает дельту и для датчиков.

Возвращает: УниФункция — селектор: Применить(ТипИнструмента) возвращает значение из ОтелВременнаяАгрегация

НизкоеПотреблениеПамяти ​

Возвращает селектор для предпочтения lowmemory (спецификация OTLP Metric Exporter, переменная OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE): дельта для counter и histogram (синхронные счётчик и гистограммы, включая экспоненциальную), кумулятивная агрегация — для остальных типов. Дельта-потоки синхронных инструментов не хранят серии между сборами.

Возвращает: УниФункция — селектор: Применить(ТипИнструмента) возвращает значение из ОтелВременнаяАгрегация

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

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

  • ТипИнструментаДляВида — тип инструмента для селектора по виду инструмента ("Counter" → "counter", "Histogram" → "histogram"); вызывает периодический читатель;
  • ОпределитьТипИнструментаПоТипуМетрики — тип инструмента по типу метрики и признаку монотонности; вызывает OTLP-экспортёр для данных без временной агрегации.

Пример ​

bsl
// Дельта для счетчиков, гистограмм и датчиков, кумулятивная - для реверсивных счетчиков
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерМетрик(Транспорт, ОтелСелекторВременнойАгрегации.ПредпочтительноДельта());
Читатель = Новый ОтелПериодическийЧитательМетрик(Экспортер);

// Временная агрегация селектора для типа инструмента
Селектор = ОтелСелекторВременнойАгрегации.НизкоеПотреблениеПамяти();
Временность = Селектор.Применить("observable_counter"); // ОтелВременнаяАгрегация.Кумулятивная()

Свой селектор — класс с функцией Применить, файл СелекторДельтаГистограмм.os:

bsl
// Дельта только для гистограмм
Функция Применить(ТипИнструмента) Экспорт
    Если ТипИнструмента = "histogram" Тогда
        Возврат ОтелВременнаяАгрегация.Дельта();
    КонецЕсли;
    Возврат ОтелВременнаяАгрегация.Кумулятивная();
КонецФункции
bsl
ПодключитьСценарий("СелекторДельтаГистограмм.os", "СелекторДельтаГистограмм");
Экспортер = Новый ОтелЭкспортерМетрик(Транспорт, Новый СелекторДельтаГистограмм());

См. также ​