ОтелПериодическийЧитательМетрик
Периодический читатель метрик — собирает метрики по расписанию и отправляет их экспортёру.
Описание
ОтелПериодическийЧитательМетрик реализует push-модель сбора метрик. Периодически собирает данные из всех зарегистрированных метров и передаёт их экспортёру.
У читателя свои потоки метрик: сбор этим читателем не влияет на данные других читателей провайдера. Агрегацию и лимит мощности по умолчанию читатель задаёт для каждого вида инструмента, временную агрегацию (cumulative/delta) — селектор экспортёра (ПолучитьВременнуюАгрегацию). Дельта-интервал начинается в момент сбора. Сборы сериализуются: callback-и и интервалы одного сбора завершаются до начала следующего, данные сборов передаются экспортёру в порядке сборов.
Каждый вызов Экспортировать ограничен таймаутом экспорта (ТаймаутЭкспортаМс, по умолчанию 30000 мс, OTEL_METRIC_EXPORT_TIMEOUT) и оставшимся сроком сброса. Если задан МаксРазмерПакетаЭкспорта, данные сбора экспортируются последовательно пакетами не больше этого числа точек; после истечения срока оставшиеся пакеты не экспортируются.
Создаётся через ОтелПостроительПровайдераМетрик.
Параметры конструктора:
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Экспортер | ОтелЭкспортерМетрик | — | Экспортёр метрик |
ИнтервалЭкспортаМс | Число | 60000 | Интервал периодического экспорта |
НовыйЛимитМощности | Число | 2000 | Лимит мощности по умолчанию для всех видов инструментов |
НоваяАгрегацияГистограмм | Строка | Неопределено | Агрегация по умолчанию для вида Histogram; Неопределено — агрегация экспортера, а без нее "explicit_bucket_histogram" |
Методы
ДобавитьМетр
Регистрирует метр в читателе.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Метр | ОтелМетр | — | Метр для регистрации |
ДобавитьПродюсер
Регистрирует дополнительный продюсер метрик (MetricProducer). При сборе читатель вызывает его функцию Произвести(Ресурс, ТаймаутМс) с ресурсом провайдера, у которого зарегистрирован (без провайдера — с ресурсом по умолчанию), и временем до срока СброситьБуфер, Закрыть или ПринудительноВыгрузитьСРезультатом (0 — без ограничения, например при периодическом сборе). Продюсер, не успевающий за это время, возвращает результат со статусом Timeout. Метрики продюсера должны содержать одну область инструментирования, идентифицирующую продюсер.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Продюсер | ИнтерфейсПродюсерМетрик | — | Продюсер метрик: Произвести(Ресурс, ТаймаутМс) возвращает ОтелРезультатПроизводстваМетрик |
Запустить
Запускает фоновый периодический сбор метрик.
ПериодическийСбор
Метод фонового задания, запускаемого Запустить(): по истечении каждого интервала собирает и экспортирует метрики, пока читатель не закрыт. Напрямую не вызывается. Интервал ожидается короткими паузами, поэтому Закрыть() останавливает задание сразу, не дожидаясь конца интервала.
СброситьБуфер
Собирает метрики читателя и экспортирует их. Сбой сбора одного метра, инструмента, callback-а или продюсера не прерывает сбор остальных: их данные экспортируются, а результат сообщает об ошибке; callback или продюсер, не уложившийся в таймаут, дает результат-таймаут. После Закрыть() возвращает ошибку. Сборы выполняются по очереди: сбор, уже идущий в другом потоке (например, фоновый), ждут не дольше срока, иначе возвращается таймаут.
Срок ограничивает и сам сбор: callback получает таймаут не больше времени до срока, продюсер — время до срока, после срока callback-и и продюсеры не вызываются, а собранные данные не экспортируются (результат — таймаут). Экспорт получает время, оставшееся после сбора.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ТаймаутМс | Число | 0 | Срок экспорта в миллисекундах (0 — без ограничения); вызов Экспортировать получает меньший из срока и ТаймаутЭкспортаМс |
Возвращает: ОтелРезультатЭкспорта — ошибка, если сбор метра или инструмента завершился сбоем или экспорт пакета не удался; иначе таймаут, если экспорт не уложился в срок; иначе успех
СброситьБуферБезОчистки
Оставлен для совместимости: то же, что СброситьБуфер — у каждого читателя свои потоки, очищать общие данные не требуется.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ТаймаутМс | Число | 0 | Таймаут экспорта в миллисекундах (0 — без ограничения) |
Возвращает: ОтелРезультатЭкспорта
Закрыть
Останавливает периодический сбор, выполняет финальный сбор и экспорт и закрывает экспортёр — в пределах общего срока. Экспортёр закрывается и после сбоя финального экспорта. Повторный вызов возвращает ошибку «Reader закрыт».
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ТаймаутМс | Число | 30000 | Таймаут завершения в миллисекундах (0 — без ограничения) |
ОчищатьДанные | Булево | Истина | Не используется, оставлен для совместимости |
Возвращает: ОтелРезультатЗакрытия — ошибка финального экспорта или закрытия экспортёра; иначе таймаут, если истёк срок; иначе успех
ПринудительноВыгрузитьСРезультатом
ForceFlush читателя: собирает и экспортирует метрики (СброситьБуфер) и вызывает ForceFlush экспортёра (ПринудительноВыгрузитьСРезультатом, у экспортёра без него — СброситьБуфер) — даже если срок уже истёк. Провайдер вызывает этот метод у каждого читателя. После Закрыть() возвращает ошибку.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ТаймаутМс | Число | 30000 | Таймаут операции в миллисекундах (0 — без ограничения) |
Возвращает: ОтелРезультатЗакрытия — ошибка, если сбор, экспорт или ForceFlush экспортёра завершились сбоем; иначе таймаут, если истёк срок или экспортёр сообщил о таймауте; иначе успех
ТаймаутЭкспортаМс
Возвращает таймаут одного вызова Экспортировать (exportTimeoutMillis).
Возвращает: Число — таймаут в миллисекундах, 0 — без ограничения. По умолчанию 30000
УстановитьТаймаутЭкспортаМс
Задаёт таймаут одного вызова Экспортировать (exportTimeoutMillis). Автоконфигурация берёт его из OTEL_METRIC_EXPORT_TIMEOUT.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Значение | Число | — | Таймаут в миллисекундах, 0 — без ограничения |
МаксРазмерПакетаЭкспорта
Возвращает максимальное число точек данных в одном вызове Экспортировать (maxExportBatchSize).
Возвращает: Число — 0 (по умолчанию) — без ограничения
УстановитьМаксРазмерПакетаЭкспорта
Задаёт максимальное число точек данных в одном вызове Экспортировать (maxExportBatchSize). Данные сбора делятся на полные пакеты этого размера (точки одной метрики могут попасть в разные пакеты), пакеты экспортируются последовательно.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Значение | Число | — | Максимальное число точек, 0 — без ограничения |
ЛимитМощности
Возвращает лимит мощности (cardinality limit) читателя по умолчанию для всех видов инструментов.
Возвращает: Число
ЛимитМощностиДляВида
Возвращает лимит мощности читателя для вида инструмента: заданный УстановитьЛимитМощностиДляВида или общий ЛимитМощности(). Применяется к потокам, для которых View не задал лимит.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ВидИнструмента | Строка | — | Counter, UpDownCounter, Histogram, Gauge, ObservableCounter, ... |
Возвращает: Число
УстановитьЛимитМощностиДляВида
Задаёт лимит мощности читателя для вида инструмента. Действует для инструментов, созданных после вызова.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ВидИнструмента | Строка | — | Вид инструмента |
Лимит | Число | — | Лимит мощности |
АгрегацияГистограммПоУмолчанию
Возвращает агрегацию гистограмм по умолчанию для данного читателя: АгрегацияПоУмолчанию("Histogram").
Возвращает: Строка — "explicit_bucket_histogram" или "base2_exponential_bucket_histogram"
АгрегацияПоУмолчанию
Возвращает агрегацию читателя по умолчанию для вида инструмента. Применяется к потокам, для которых View не задал агрегацию. Агрегация берётся по порядку:
- заданная читателю —
УстановитьАгрегациюПоУмолчаниюили агрегация гистограмм конструктора; - заданная экспортером — его функция
АгрегацияПоУмолчанию(ВидИнструмента), если она есть (у ОтелЭкспортерМетрик — агрегация гистограммOTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION); - агрегация спецификации для вида инструмента.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ВидИнструмента | Строка | — | Вид инструмента |
Возвращает: Строка — "sum", "last_value", "explicit_bucket_histogram", "drop", ...; "default" для неизвестного вида
УстановитьАгрегациюПоУмолчанию
Задаёт агрегацию читателя по умолчанию для вида инструмента. Действует для инструментов, созданных после вызова. Агрегация, несовместимая с видом (например, гистограмма для асинхронного инструмента), заменяется агрегацией спецификации с предупреждением.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ВидИнструмента | Строка | — | Вид инструмента |
Агрегация | Строка, Соответствие | — | Агрегация (ОтелАгрегация.Сумма(), "drop", ...) |
ВременнаяАгрегацияДляВида
Возвращает временную агрегацию потоков читателя для вида инструмента — её задаёт селектор экспортёра. Экспортёр без ПолучитьВременнуюАгрегацию получает кумулятивную.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ВидИнструмента | Строка | — | Вид инструмента |
Возвращает: Число — значение из ОтелВременнаяАгрегация
Внутренние методы
Экспортированы только для вызова из других модулей SDK (в OneScript нет внутренней видимости), приложению вызывать их не нужно:
ЗарегистрироватьУПровайдера— регистрирует читатель у провайдера при его создании и запоминает ресурс провайдера для продюсеров метрик. Читатель регистрируется только у одного провайдера: повторный вызов пишет ошибку в лог и возвращаетЛожь, и провайдер такой читатель не добавляет.
Пример
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерМетрик(Транспорт);
ПериодическийЧитатель = Новый ОтелПериодическийЧитательМетрик(Экспортер, 60000);
Построитель = Новый ОтелПостроительПровайдераМетрик();
Построитель.ЗарегистрироватьЧитатель(ПериодическийЧитатель);
Провайдер = Построитель.Построить();
// Запустить периодический сбор
ПериодическийЧитатель.Запустить();
// При завершении
ПериодическийЧитатель.Закрыть(5000);