ОтелМетр
Метр (Meter) — фабрика метрических инструментов.
Описание
ОтелМетр создаёт и возвращает инструменты для записи метрик: счётчики, датчики, гистограммы и наблюдаемые инструменты. Инструменты кэшируются по нормализованному имени.
При повторной регистрации с тем же именем (без учёта регистра), тем же видом и той же единицей измерения возвращается уже существующий инструмент; конфликт описания или advisory-параметров логируется как предупреждение.
Если при повторной регистрации отличается вид инструмента или единица измерения, возвращается отдельный инструмент запрошенного вида с именем первой регистрации. Его данные экспортируются отдельной метрикой, в лог пишется предупреждение. Повторный вызов с теми же параметрами возвращает этот же инструмент.
Все публичные методы потокобезопасны.
Имя инструмента должно соответствовать паттерну [A-Za-z][A-Za-z0-9_./-]{0,254}.
Методы
СоздатьСчетчик
Создаёт монотонный счётчик (ОтелСчетчик) — принимает только неотрицательные значения.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Имя | Строка | — | Имя счётчика |
Описание | Строка | "" | Описание |
ЕдиницаИзмерения | Строка | "" | Единица измерения |
Совет | Структура, Неопределено | Неопределено | Advisory-параметры |
Возвращает: ОтелСчетчик
СоздатьРеверсивныйСчетчик
Создаёт реверсивный счётчик (ОтелРеверсивныйСчетчик) — принимает любые значения, включая отрицательные (UpDownCounter).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Имя | Строка | — | Имя счётчика |
Описание | Строка | "" | Описание |
ЕдиницаИзмерения | Строка | "" | Единица измерения |
Совет | Структура, Неопределено | Неопределено | Advisory-параметры |
Возвращает: ОтелРеверсивныйСчетчик
СоздатьДатчик
Создаёт датчик (ОтелДатчик) — записывает мгновенное значение, перезаписывая предыдущее (Gauge).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Имя | Строка | — | Имя датчика |
Описание | Строка | "" | Описание |
ЕдиницаИзмерения | Строка | "" | Единица измерения |
Совет | Структура, Неопределено | Неопределено | Advisory-параметры |
Возвращает: ОтелДатчик
СоздатьГистограмму
Создаёт гистограмму (ОтелГистограмма) — агрегирует значения по бакетам (Histogram).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Имя | Строка | — | Имя гистограммы |
Описание | Строка | "" | Описание |
ЕдиницаИзмерения | Строка | "" | Единица измерения |
Совет | Структура, Неопределено | Неопределено | Advisory-параметры: ключ ГраницыГистограммы — границы бакетов (ExplicitBucketBoundaries) |
Возвращает: ОтелГистограмма
Экспоненциальная гистограмма — не отдельный инструмент, а агрегация инструмента Histogram (спецификация Metrics SDK, Base2 Exponential Bucket Histogram Aggregation). Чтобы гистограмма агрегировалась экспоненциальной гистограммой, создайте её через СоздатьГистограмму и задайте агрегацию:
- View с
ОтелАгрегация.ГистограммаЭкспоненциальная(МаксБакетов, МаксШкала)— для выбранных инструментов; - агрегацию гистограмм по умолчанию у экспортера или читателя (
default_histogram_aggregation: base2_exponential_bucket_histogram,OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION) — для всех гистограмм.
Метод СоздатьЭкспоненциальнуюГистограмму и класс ОтелЭкспоненциальнаяГистограмма из версий 1.x удалены: вид инструмента ExponentialHistogram в спецификации не определён.
// Было (1.x): Метр.СоздатьЭкспоненциальнуюГистограмму("db.query.duration", "Время запроса", "ms", 64)
Селектор = Новый ОтелСелекторИнструментов("db.query.duration");
Представление = Новый ОтелПредставление(, , , , ОтелАгрегация.ГистограммаЭкспоненциальная(64));
Провайдер.ЗарегистрироватьПредставление(Селектор, Представление);
Гистограмма = Провайдер.ПолучитьМетр("db").СоздатьГистограмму("db.query.duration", "Время запроса", "ms");СоздатьНаблюдаемыйСчетчик
Создаёт наблюдаемый счётчик (ОтелНаблюдаемыйСчетчик). Значения собираются через callback при каждом сборе метрик.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Имя | Строка | — | Имя инструмента |
Callback | Действие, Массив, Неопределено | Неопределено | Callback для сбора значений или массив callback |
Описание | Строка | "" | Описание |
ЕдиницаИзмерения | Строка | "" | Единица измерения |
Совет | Структура, Неопределено | Неопределено | Advisory-параметры |
Возвращает: ОтелНаблюдаемыйСчетчик
СоздатьНаблюдаемыйРеверсивныйСчетчик
Создаёт наблюдаемый реверсивный счётчик (ОтелНаблюдаемыйРеверсивныйСчетчик).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Имя | Строка | — | Имя инструмента |
Callback | Действие, Массив, Неопределено | Неопределено | Callback для сбора значений или массив callback |
Описание | Строка | "" | Описание |
ЕдиницаИзмерения | Строка | "" | Единица измерения |
Совет | Структура, Неопределено | Неопределено | Advisory-параметры |
Возвращает: ОтелНаблюдаемыйРеверсивныйСчетчик
СоздатьНаблюдаемыйДатчик
Создаёт наблюдаемый датчик (ОтелНаблюдаемыйДатчик).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Имя | Строка | — | Имя инструмента |
Callback | Действие, Массив, Неопределено | Неопределено | Callback для сбора значений или массив callback |
Описание | Строка | "" | Описание |
ЕдиницаИзмерения | Строка | "" | Единица измерения |
Совет | Структура, Неопределено | Неопределено | Advisory-параметры |
Возвращает: ОтелНаблюдаемыйДатчик
ЗарегистрироватьОбратныйВызов
Регистрирует один callback для нескольких наблюдаемых инструментов этого метра (multi-instrument callback). Регистрация с синхронным инструментом или инструментом другого метра отклоняется с предупреждением в логе. Наблюдения одного вызова callback получают одно время для всех инструментов.
Наблюдение инструмента в Соответствие callback-а доступно и по самому инструменту, и по его имени. Одноимённые инструменты разного вида или единицы различаются только по инструменту: по имени доступно наблюдение первого из них в списке. Инструмент, указанный в списке дважды, наблюдается один раз.
Процедура НаблюдатьЗадержку(Наблюдения, Датчики) Экспорт
Наблюдения.Получить(Датчики.Миллисекунды).Записать(1500);
Наблюдения.Получить(Датчики.Секунды).Записать(1.5);
КонецПроцедуры| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Callback | Действие | — | Вызывается с Соответствие (инструмент или имя инструмента → ОтелНаблюдениеМетрики), вторым аргументом — Состояние, если оно задано |
НовыеИнструменты | Массив | — | Наблюдаемые (асинхронные) инструменты этого метра |
Состояние | Произвольный | Неопределено | Состояние регистрации, передаётся в каждый вызов |
Возвращает: ОтелРегистрацияНаблюдателя — токен регистрации: Закрыть() отменяет её. У отклонённой регистрации Закрыть() ничего не делает.
ТаймаутОбратныхВызововМс
Возвращает таймаут callback-ов асинхронных инструментов метра и мульти-callback-ов.
Возвращает: Число — таймаут в миллисекундах, 0 — без таймаута. По умолчанию 30000
УстановитьТаймаутОбратныхВызововМс
Задаёт таймаут callback-ов асинхронных инструментов метра и мульти-callback-ов. Применяется к созданным и создаваемым инструментам. Callback выполняется в фоновом задании: не завершившийся за таймаут callback не задерживает сбор, его наблюдения отбрасываются с предупреждением в логе. Фоновое задание OneScript нельзя прервать (OneScript#1672): оно продолжает работу, и до его завершения сбор инструментов этого callback-а не начинается — сборы пропускают их с предупреждением и таймаутом в результате: не вызываются ни остальные callback-и инструмента, ни мульти-callback-и с ним (callback-и инструмента должны завершиться до следующего раунда его сбора).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Значение | Число | — | Таймаут в миллисекундах; 0 — callback-и выполняются в потоке сбора без таймаута |
ОбластьИнструментирования
Возвращает область инструментирования метра (InstrumentationScope): имя, версию, адрес схемы и атрибуты, с которыми метр получен через ПолучитьМетр провайдера или ОтелПостроительМетра. По области провайдер кэширует метры, а селекторы View (ОтелСелекторИнструментов) сравнивают с ней критерии ИмяМетра, ВерсияМетра и АдресСхемыМетра.
Возвращает: ОтелОбластьИнструментирования
Требования к callback
Для callback наблюдаемых инструментов и ЗарегистрироватьОбратныйВызов (спецификация Metrics API):
- callback должен быть реентерабельным: SDK вызывает callback-и для каждого
MetricReaderотдельно, в том числе параллельно из разных потоков; - callback не должен выполняться неограниченное время — без сетевых вызовов, ожидания блокировок и тяжёлого ввода-вывода, иначе сбор метрик задерживается до таймаута (
УстановитьТаймаутОбратныхВызововМс), а наблюдения callback-а теряются; - callback-и не должны делать дублирующие наблюдения (несколько измерений с одинаковыми атрибутами) по всем callback-ам инструмента — собственным и мульти-callback-ам;
- исключение callback перехватывается SDK и пишется в лог, сбор по остальным callback-ам продолжается.
Внутренние методы
Экспортированы только для вызова из других модулей SDK (в OneScript нет внутренней видимости), приложению вызывать их не нужно:
УстановитьМетрВключен— включает или выключает метр: провайдер выключает no-op метр, который выдаёт после закрытия и пока он выключен (no-op SDK). No-op метр не проверяет параметры и не пишет в лог, его инструменты выключены, не регистрируются в метре и не хранят измерений, мульти-callback-и не регистрируются;УстановитьЧитателей— задаёт читателей провайдера: у каждого читателя свои потоки инструментов;УстановитьПредставления— задаёт View провайдера и заново разрешает потоки инструментов; о View сНовоеИмяи селектором без точного имени пишет предупреждение в лог;УстановитьАгрегациюГистограммПоУмолчанию— задаёт агрегацию гистограмм по умолчанию для потоков метра без читателей (передаёт провайдер);СобратьДляЧитателя— собирает метрики метра для читателя: вызывает callback-и и мульти-callback-и и собирает потоки читателя;УдалитьCallback— отменяет регистрацию мульти-callback-а, вызывается изЗакрыть()ОтелРегистрацияНаблюдателя;ОтключитьИнструменты— отключает синхронные инструменты метра при закрытии провайдера (callback-и наблюдаемых нужны финальному сбору читателей). После этого метр создаёт синхронные инструменты отключёнными, наблюдаемые — no-op, а мульти-callback-и отклоняет: новые callback-и не сохраняются.
Остальные экспортные методы другие модули SDK не вызывают, приложению они тоже не нужны:
ОбновитьПотоки— заново разрешает потоки инструментов после изменения View, читателей или агрегации по умолчанию; его вызываютУстановитьЧитателей,УстановитьПредставленияиУстановитьАгрегациюГистограммПоУмолчанию;Включен—Ложьу no-op метра выключенного или закрытого провайдера: такой метр не даёт данных при сборе;ПолучитьПредставления— возвращает View метра: пары с ключамиСелекториПредставление;Инструменты— возвращает созданные инструменты метра;Ресурс— возвращает ресурс, с которым создан метр (ресурс провайдера): он попадает в данные метрик;УстановитьЛимитМощности— задаёт лимит мощности потоков метра без читателей (по умолчанию 2000) для инструментов, созданных после вызова;УстановитьЛог— подменяет логгер метра (используется в тестах);ВызватьМультиОбратныеВызовы— вызывает мульти-callback-и и передаёт наблюдения инструментам для прямого сбора без читателя (используется в тестах); читатели получают наблюдения мульти-callback-ов черезСобратьДляЧитателя.
Пример
Метр = Провайдер.ПолучитьМетр("мой-сервис", "1.0.0");
// Синхронные инструменты
Счетчик = Метр.СоздатьСчетчик("http.requests.total", "Всего HTTP-запросов", "{запросов}");
Гистограмма = Метр.СоздатьГистограмму("http.request.duration", "Длительность запроса", "s");
Датчик = Метр.СоздатьДатчик("system.memory.usage", "Использование памяти", "By");
// Наблюдаемый инструмент с callback
ОбратныйВызов = Новый Действие(ЭтотОбъект, "МойCallback");
НаблюдаемыйДатчик = Метр.СоздатьНаблюдаемыйДатчик(
"queue.size", ОбратныйВызов, "Размер очереди", "{элементов}");