Autumn Docs

ОтелНаблюдаемыйСчетчик ​

Наблюдаемый счётчик (ObservableCounter) — асинхронный монотонный инструмент для суммирования.

Описание ​

ОтелНаблюдаемыйСчетчик реализует спецификацию OpenTelemetry ObservableCounter. Значения собираются через зарегистрированные callback при каждом сборе метрик. Все методы, включая добавление и удаление callback-ов, безопасны для конкурентного вызова из нескольких потоков. Требования к callback — в ОтелМетр.

Используется, когда нет возможности записать значение непосредственно в момент изменения (например, системные счётчики из ОС).

Thin facade — вся логика в ОтелБазовыйНаблюдаемыйИнструмент.

Методы ​

Вид определён в самом классе, остальные методы унаследованы от ОтелБазовыйНаблюдаемыйИнструмент.

Вид ​

Возвращает вид инструмента.

Возвращает: Строка — "ObservableCounter"

ДобавитьCallback ​

Регистрирует дополнительный callback для наблюдения. Повторная регистрация того же callback игнорируется. Callback SHOULD NOT бросать исключения — они будут перехвачены и залогированы.

ПараметрТипПо умолчаниюОписание
CallbackДействие—Callback с сигнатурой (Наблюдение: ОтелНаблюдениеМетрики)
СостояниеПроизвольныйНеопределеноСостояние регистрации. Если задано, callback вызывается с двумя аргументами: (Наблюдение, Состояние)

Возвращает: ОтелРегистрацияНаблюдателя — токен регистрации: Закрыть() отменяет её (то же, что УдалитьCallback).

Callback-и, переданные при повторном создании идентичного инструмента (СоздатьНаблюдаемыйСчетчик с тем же именем, видом и единицей), тоже регистрируются у ранее созданного инструмента.

УдалитьCallback ​

Удаляет ранее зарегистрированный callback — добавленный ДобавитьCallback или переданный при создании инструмента. Callback ищется по ссылке: нужен тот же объект Действие, что и при регистрации. Если такого callback нет, ничего не делает.

ПараметрТипПо умолчаниюОписание
CallbackДействие—Callback для удаления

Имя ​

Возвращает имя инструмента. Если имя уже было зарегистрировано в метре в другом регистре, возвращается имя первой регистрации. View с НовоеИмя меняет имя метрики в экспорте, а не имя инструмента.

Возвращает: Строка

Описание ​

Возвращает описание, с которым создан инструмент.

Возвращает: Строка — пустая строка, если описание не задано

ЕдиницаИзмерения ​

Возвращает единицу измерения, с которой создан инструмент.

Возвращает: Строка — пустая строка, если единица не задана

Внутренние методы ​

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

  • СобратьДляЧитателя — вызывает callback-и инструмента и собирает его потоки для читателя (вызывает ОтелМетр.СобратьДляЧитателя);
  • ЕстьНезавершенныйCallback — Истина, пока выполняется задание callback-а, не уложившееся в таймаут прошлого сбора: метр пропускает сбор инструмента;
  • УстановитьТаймаутCallbackМс — задаёт таймаут callback-ов инструмента (метр передаёт свой таймаут);
  • ЭтоНаблюдаемыйИнструмент — всегда Истина: по нему метр отличает асинхронные инструменты от синхронных;
  • ДобавитьВнешниеНаблюдения — принимает наблюдения мульти-callback-а для сбора без читателя (ОтелМетр.ВызватьМультиОбратныеВызовы); вне вызова мульти-callback-а игнорирует их с предупреждением;
  • УстановитьВыполняетсяCallback — разрешает и запрещает ДобавитьВнешниеНаблюдения на время вызова мульти-callback-а;
  • ОчиститьТочкиДанных — сбрасывает накопленные наблюдения мульти-callback-ов для сбора без читателя;
  • Хранилища, УстановитьХранилища — возвращают и заменяют хранилища потоков инструмента (поток на читателя и View): метр задаёт их при создании инструмента и после изменения View или читателей;
  • Дескриптор, УстановитьДескриптор — дескриптор инструмента (имя, вид, единица, advisory-параметры), по которому метр разрешает потоки.

Остальные экспортные методы SDK не вызывает, их используют тесты; приложению они не нужны:

  • Собрать — вызывает callback-и и возвращает кумулятивные данные первого потока вместе с наблюдениями, переданными ДобавитьВнешниеНаблюдения;
  • УстановитьЛимитМощности — задаёт лимит мощности всех потоков (потокам метра его задают View, читатель или сам метр);
  • ТаймаутCallbackМс — возвращает таймаут callback-ов инструмента в миллисекундах (0 — без таймаута).

Пример ​

bsl
// Callback для наблюдения
Процедура СобратьМетрики(Наблюдение) Экспорт
    // системный счётчик CPU ticks
    ЗначениеСчетчика = ПолучитьСчетчикЦПУ();
    Наблюдение.Записать(ЗначениеСчетчика);
КонецПроцедуры

// Дополнительный callback: время ЦП в режиме ядра
Процедура СобратьМетрикиЯдра(Наблюдение) Экспорт
    Атрибуты = Новый ОтелАтрибуты();
    Атрибуты.Установить("cpu.mode", "system");
    Наблюдение.Записать(ПолучитьСчетчикЦПУЯдра(), Атрибуты);
КонецПроцедуры

НаблюдаемыйСчетчик = Метр.СоздатьНаблюдаемыйСчетчик(
    "system.cpu.time",
    Новый Действие(ЭтотОбъект, "СобратьМетрики"),
    "Время ЦП",
    "s");

// Добавить ещё один callback
ДополнительныйCallback = Новый Действие(ЭтотОбъект, "СобратьМетрикиЯдра");
Регистрация = НаблюдаемыйСчетчик.ДобавитьCallback(ДополнительныйCallback);

// Отменить callback
Регистрация.Закрыть();