ОтелГистограмма
Гистограмма (Histogram) — инструмент для статистики распределения значений.
Описание
ОтелГистограмма реализует спецификацию OpenTelemetry Histogram. По умолчанию агрегирует значения в явные бакеты с фиксированными границами; читатель может задать для гистограмм экспоненциальную агрегацию (например, по OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION), а View — другую агрегацию для отдельных инструментов. Используется для измерения распределений: длительность операций, размеры запросов/ответов и т.д. Все методы безопасны для конкурентного вызова из нескольких потоков.
Thin facade — логика хранения в ОтелБазовыйСинхронныйИнструмент.
Границы бакетов задаются при создании через advisory-параметр ExplicitBucketBoundaries — ключ ГраницыГистограммы структуры Совет — или через ОтелПредставление. Границы MUST быть строго монотонно возрастающими.
Методы
Записать и Вид определены в самом классе, остальные методы унаследованы от ОтелБазовыйСинхронныйИнструмент.
Записать
Записывает значение в гистограмму. Ожидается неотрицательное значение.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Значение | Число | — | Измеренное значение (ожидается неотрицательное) |
Атрибуты | ОтелАтрибуты | Неопределено | Атрибуты точки данных |
Контекст | Соответствие, Неопределено | Неопределено | Явный контекст |
Включен
Проверяет, включён ли инструмент — записывает ли он измерения (спецификация Metrics API, раздел Enabled). У выключенного инструмента Записать ничего не записывает, поэтому по результату можно не вычислять атрибуты и значение измерения.
Возвращает Ложь, если:
- инструмент отключён закрытием провайдера:
Закрыть()провайдера отключает инструменты его метров, в том числе созданные после закрытия; - инструмент создан no-op метром: его выдаёт закрытый провайдер и no-op провайдер, пока SDK не настроен;
- все потоки инструмента используют агрегацию Drop (
ОтелАгрегация.Отбросить()): её задаёт View или агрегация читателя по умолчанию для вида инструмента.
Иначе возвращает Истина.
Вызывайте Включен перед каждой записью измерения и не кэшируйте результат: он может измениться во время работы, например после регистрации View или закрытия провайдера.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Атрибуты | ОтелАтрибуты, Неопределено | Неопределено | Зарезервирован для будущих версий, на результат не влияет |
Возвращает: Булево — Истина, если инструмент записывает измерения
Вид
Возвращает вид инструмента.
Возвращает: Строка — "Histogram"
Имя
Возвращает имя инструмента. Если имя уже было зарегистрировано в метре в другом регистре, возвращается имя первой регистрации. View с НовоеИмя меняет имя метрики в экспорте, а не имя инструмента.
Возвращает: Строка
Описание
Возвращает описание, с которым создан инструмент.
Возвращает: Строка — пустая строка, если описание не задано
ЕдиницаИзмерения
Возвращает единицу измерения, с которой создан инструмент.
Возвращает: Строка — пустая строка, если единица не задана
Внутренние методы
Экспортированы только для вызова из других модулей SDK (в OneScript нет внутренней видимости), приложению вызывать их не нужно:
СобратьДляЧитателя— собирает потоки инструмента для читателя (вызываетОтелМетр.СобратьДляЧитателя);Отключить— отключает инструмент: измерения больше не записываются,ВключенвозвращаетЛожь(метр вызывает его при закрытии провайдера);Хранилища,УстановитьХранилища— возвращают и заменяют хранилища потоков инструмента (поток на читателя и View): метр задаёт их при создании инструмента и после изменения View или читателей;Дескриптор,УстановитьДескриптор— дескриптор инструмента (имя, вид, единица, advisory-параметры), по которому метр разрешает потоки;УстановитьМетрВключен— передаёт инструменту общий с метром флаг включённости (метр — при создании инструмента).
Остальные экспортные методы SDK не вызывает, их используют тесты; приложению они не нужны:
Собрать— возвращает данные первого потока инструмента, не начиная новый интервал сбора;ОчиститьТочкиДанных— завершает интервал сбора всех потоков: при дельта-временности начинает новый интервал, при кумулятивной сбрасывает exemplars;КоличествоСерий— возвращает количество серий атрибутов первого потока;УстановитьЛимитМощности— задаёт лимит мощности всех потоков (потокам метра его задают View, читатель или сам метр);УстановитьФильтрЭкземпляров— задаёт фильтр exemplars всех потоков (потокам метра его задаёт провайдер);УстановитьФабрикуРезервуаров— задаёт фабрику резервуаров exemplars всех потоков;УстановитьРезервуарЭкземпляров— устаревший вариант: один резервуар exemplars на все серии потока, пишет предупреждение в лог;УстановитьРазрешенныеКлючиАтрибутов,УстановитьИсключенныеКлючиАтрибутов— задают фильтр ключей атрибутов всех потоков (потокам метра его задаёт View).
Пример
ДлительностьЗапроса = Метр.СоздатьГистограмму(
"http.request.duration", "Длительность HTTP-запроса", "s");
НачалоМс = ТекущаяУниверсальнаяДатаВМиллисекундах();
ОбработатьЗапрос();
ДлительностьСек = (ТекущаяУниверсальнаяДатаВМиллисекундах() - НачалоМс) / 1000;
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("http.method", "POST");
Атрибуты.Установить("http.route", "/api/orders");
ДлительностьЗапроса.Записать(ДлительностьСек, Атрибуты);
// Дорогие атрибуты вычисляются, только если гистограмма включена.
// Включен вызывается перед каждой записью: результат может измениться
Если ДлительностьЗапроса.Включен() Тогда
ДлительностьЗапроса.Записать(ДлительностьСек, ВычислитьАтрибутыЗапроса());
КонецЕсли;