Публичный интерфейс библиотеки `opentelemetry`

Ядро

ОтелSdk — главный класс SDK, единая точка входа в телеметрию
ОтелПостроительSdk — построитель SDK (fluent API)
ОтелГлобальный — модуль глобального реестра OpenTelemetry
ОтелАтрибуты — хранилище пар ключ-значение для телеметрии
ОтелРесурс — описание сущности, производящей телеметрию
ОтелРесурсы — фабрика ресурсов: по умолчанию, из детекторов, из окружения
ОтелПостроительРесурса — построитель ресурса (fluent API)
ИнтерфейсДетекторРесурса — контракт детектора ресурса, встроенного или своего
ОтелДетекторРесурсаХоста — детектор ресурса хоста: имя компьютера и тип ОС
ОтелДетекторРесурсаПроцесса — детектор ресурса процесса: идентификатор процесса
ОтелДетекторРесурсаПроцессора — детектор ресурса процессора: модель и архитектура
ОтелДетекторРесурсаКонтейнера — детектор ресурса контейнера: идентификатор контейнера
ОтелДетекторРесурсаЭкземпляраСервиса — детектор ресурса экземпляра сервиса: идентификатор экземпляра
ОтелОбластьИнструментирования — InstrumentationScope: описание библиотеки инструментации
ОтелКонтекст — модуль управления текущим контекстом выполнения
ОтелКлючКонтекста — ключ для хранения значений в контексте
ОтелТокенКонтекста — токен, возвращаемый при присоединении контекста
ОтелBaggage — передача контекстных данных между сервисами (W3C Baggage)
ОтелПостроительBaggage — построитель Baggage (fluent API)
ОтелСемантическиеСоглашения — модуль констант семантических соглашений: имена атрибутов и метрик db., server., error.type, code.*
ОтелРезультатЭкспорта — результат операции экспорта или принудительной выгрузки
ОтелРезультатыЭкспорта — модуль создания результатов экспорта: успех, ошибка, таймаут, сведение нескольких результатов
ОтелРезультатЗакрытия — результат операции закрытия / принудительной выгрузки
ОтелРезультатыЗакрытия — модуль создания результатов закрытия: успех, ошибка, таймаут
ОтелУтилиты — время в формате OpenTelemetry (строка наносекунд), часы SDK и генератор идентификаторов

Трассировка

ОтелПровайдерТрассировки — провайдер трассировки SDK
ОтелПостроительПровайдераТрассировки — построитель провайдера трассировки
ОтелТрассировщик — создание и управление спанами
ОтелПостроительТрассировщика — построитель трассировщика: версия, адрес схемы и атрибуты области
ОтелСпан — единица работы или операции в трассировке
ОтелПостроительСпана — построитель спана (SpanBuilder)
ОтелНезаписывающийСпан — незаписывающий спан (NonRecordingSpan), служебный класс, напрямую не создаётся
ОтелСпаны — модуль: незаписывающий спан из контекста спана и невалидный спан
ОтелКонтекстСпана — контекст спана (SpanContext)
ОтелСобытиеСпана — событие в рамках спана (SpanEvent)
ОтелЛинк — связь спана с другим спаном
ОтелЛимитыСпана — лимиты количества атрибутов, событий и линков
ОтелСостояниеТрассировки — W3C TraceState
ОтелВидСпана — модуль констант видов спана (SpanKind)
ОтелКодСтатуса — модуль констант кодов статуса спана
ОтелСэмплер — модуль: встроенные сэмплеры (AlwaysOn, AlwaysOff, TraceIdRatioBased, ParentBased, AlwaysRecord) и решения сэмплера
ИнтерфейсСэмплер — контракт сэмплера, встроенного или своего
ОтелРезультатСэмплирования — результат сэмплирования: решение, атрибуты и TraceState
ИнтерфейсПроцессорСпанов — контракт процессора спанов, встроенного или своего
ОтелПростойПроцессорСпанов — синхронный процессор спанов
ОтелПакетныйПроцессорСпанов — пакетный асинхронный процессор спанов
ОтелКомпозитныйПроцессорСпанов — цепочка процессоров спанов, которая работает как один процессор

Логирование

ОтелПровайдерЛогирования — провайдер логирования SDK
ОтелПостроительПровайдераЛогирования — построитель провайдера логирования
ОтелЛоггер — логгер для записи событий
ОтелПостроительЛоггера — построитель логгера: версия, адрес схемы и атрибуты области
ОтелЗаписьЛога — запись журнала (LogRecord)
ОтелСтепеньСерьезности — константы степени серьезности лог-записи
ОтелЛимитыЗаписейЛога — лимиты атрибутов записей лога
ИнтерфейсПроцессорЛогов — контракт процессора записей лога, встроенного или своего
ОтелПростойПроцессорЛогов — синхронный процессор записей журнала
ОтелПроцессорСобытийВСобытияСпана — перенос событий записей лога в события текущего спана
ОтелПакетныйПроцессорЛогов — пакетный процессор записей журнала
ОтелКомпозитныйПроцессорЛогов — цепочка процессоров записей лога, которая работает как один процессор

Метрики

ОтелПровайдерМетрик — провайдер метрик SDK
ОтелПостроительПровайдераМетрик — построитель провайдера метрик
ОтелМетр — метр для создания инструментов метрик
ОтелПостроительМетра — построитель метра: версия, адрес схемы и атрибуты области
ОтелСчетчик — монотонно возрастающий счетчик (Counter)
ОтелРеверсивныйСчетчик — двунаправленный счетчик (UpDownCounter)
ОтелГистограмма — гистограмма распределения (Histogram)
ОтелДатчик — синхронный датчик значений (Gauge)
ОтелНаблюдаемыйСчетчик — асинхронный счётчик (ObservableCounter)
ОтелНаблюдаемыйРеверсивныйСчетчик — асинхронный реверсивный счётчик (ObservableUpDownCounter)
ОтелНаблюдаемыйДатчик — асинхронный датчик (ObservableGauge)
ОтелНаблюдениеМетрики — объект, в который callback асинхронного инструмента записывает наблюдения
ОтелРегистрацияНаблюдателя — токен регистрации callback: отменяет регистрацию
ОтелПредставление — представление (View): имя, атрибуты и агрегация потока метрики
ОтелСелекторИнструментов — критерии выбора инструментов для представления
ОтелАгрегация — модуль агрегаций для представлений и читателей
ОтелВременнаяАгрегация — модуль констант временной агрегации (temporality)
ОтелСелекторВременнойАгрегации — модуль селекторов временной агрегации для экспортёра метрик
ОтелФильтрЭкземпляров — модуль фильтров exemplars
ОтелФабрикаПростыхРезервуаров — фабрика простых резервуаров exemplars фиксированного размера
ОтелФабрикаВыровненныхРезервуаровГистограммы — фабрика резервуаров exemplars, выровненных по бакетам гистограммы
ОтелФабрикаNoopРезервуаров — фабрика пустых резервуаров: отключает exemplars потока
ОтелРезервуарЭкземпляров — резервуар exemplars и контракт своего резервуара
ОтелПериодическийЧитательМетрик — периодическое чтение метрик для экспорта
ОтелПрометеусЧитательМетрик — читатель метрик в формате Prometheus
ИнтерфейсПродюсерМетрик — контракт продюсера метрик: внешнего источника готовых данных метрик
ОтелРезультатПроизводстваМетрик — результат продюсера метрик: статус и метрики
ОтелДанныеМетрики — данные одной метрики (MetricData) для экспортёров и продюсеров
ОтелТипМетрики — модуль констант типов метрик

Экспорт

ОтелЭкспортерСпанов — OTLP-экспортер спанов
ОтелЭкспортерЛогов — OTLP-экспортер записей журнала
ОтелЭкспортерМетрик — OTLP-экспортер метрик
ИнтерфейсЭкспортерСпанов — контракт экспортера спанов, встроенного или своего
ИнтерфейсЭкспортерЛогов — контракт экспортера записей лога
ИнтерфейсЭкспортерМетрик — контракт экспортера метрик
ОтелHttpТранспорт — HTTP-транспорт для OTLP (protobuf или JSON)
ОтелGrpcТранспорт — gRPC-транспорт для OTLP
ОтелВПамятьТранспорт — транспорт в памяти (для тестирования)
ОтелКонсольныйТранспорт — вывод OTLP JSON в стандартный вывод (экспортер console)
ОтелНастройкиTls — настройки TLS-соединения

Пропагация

ОтелW3CПропагатор — пропагатор W3C Trace Context
ОтелW3CBaggageПропагатор — пропагатор W3C Baggage
ОтелКомпозитныйПропагатор — составной пропагатор
ОтелНоопПропагатор — пустой пропагатор (noop)
ОтелГеттерТекстовойКарты — вспомогательный класс для чтения заголовков
ОтелСеттерТекстовойКарты — вспомогательный класс для записи заголовков
ОтелB3Пропагатор — пропагатор B3 (Zipkin), отдельный пакет opentelemetry-propagator-b3

Конфигурация

ОтелАвтоконфигурация — автоматическая инициализация SDK из переменных окружения или файла конфигурации
ОтелФайловаяКонфигурация — разбор YAML-файла конфигурации в модель
ОтелКонфигурация — модель файла конфигурации
ОтелКонфигурационнаяФабрика — создание SDK и его частей по модели файла конфигурации, регистрация провайдеров компонентов
ОтелТипКомпонентаКонфигурации — типы компонентов для провайдеров компонентов файла конфигурации
ОтелСвойстваКонфигурации — свойства компонента из файла конфигурации (ConfigProperties)

Интеграции

ОтелАппендерLogos — аппендер для интеграции с библиотекой логирования Logos

ОтелАппендерLogos

Аппендер logos для отправки логов через OpenTelemetry.

Описание

Реализует интерфейс аппендера библиотеки logos (oscript-library/logos), перенаправляя сообщения логирования в формате OTLP через [ОтелЛоггер].

Позволяет использовать существующую инфраструктуру логирования на основе logos и одновременно отправлять логи в OpenTelemetry-совместимые системы (Grafana Loki, Jaeger и т.д.).

Маппинг уровней logos → OTel SeverityNumber:

Уровень logos	Значение	OTel Severity	Номер
`Отладка`	0	DEBUG	5
`Информация`	1	INFO	9
`Предупреждение`	2	WARN	13
`Ошибка`	3	ERROR	17
`КритичнаяОшибка`	4	FATAL	21

Исключения, возникающие внутри аппендера, перехватываются и не распространяются в цепочку logos — это защищает логирование от сбоев OTel-инфраструктуры.

Конструктор

bsl

Новый ОтелАппендерLogos(Логгер)

Параметр	Тип	По умолчанию	Описание
`Логгер`	ОтелЛоггер	`Неопределено`	Настроенный логгер OpenTelemetry для отправки записей. Можно установить позже через `УстановитьЛоггер()`

Методы

ВывестиСобытие

Выводит событие лога через OpenTelemetry. Вызывается библиотекой logos при каждом событии логирования. Маппирует уровень, тело, временну́ю метку и дополнительные поля события.

Параметр	Тип	По умолчанию	Описание
`СобытиеЛога`	СобытиеЛога	—	Событие из библиотеки `logos`

Закрыть

Закрывает аппендер. Ресурсов, требующих явного закрытия, нет.

УстановитьСвойство

Устанавливает свойство аппендера из конфигурационного файла logos. Свойства не поддерживаются, конфигурация выполняется через конструктор.

Параметр	Тип	По умолчанию	Описание
`ИмяСвойства`	Строка	—	Имя свойства
`Значение`	Произвольный	—	Значение свойства

УстановитьЛоггер

Устанавливает OTel-логгер для отправки данных.

Параметр	Тип	По умолчанию	Описание
`Значение`	ОтелЛоггер	—	Настроенный логгер OpenTelemetry

Логгер

Возвращает текущий OTel-логгер.

Возвращает: ОтелЛоггер — логгер OpenTelemetry

Пример

bsl

#Использовать opentelemetry
#Использовать logos

// Создать OTel-логгер
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
ЭкспортерЛогов = Новый ОтелЭкспортерЛогов(Транспорт);
ПровайдерЛогирования = Новый ОтелПровайдерЛогирования(
    ОтелРесурсы.ПоУмолчанию(), Новый ОтелПростойПроцессорЛогов(ЭкспортерЛогов));

// Создать аппендер и привязать к логгеру
ОтелЛоггер = ПровайдерЛогирования.ПолучитьЛоггер("мое.приложение");
Аппендер = Новый ОтелАппендерLogos(ОтелЛоггер);

// Подключить аппендер к логу logos как способ вывода
Лог = Логирование.ПолучитьЛог("мое.приложение");
Лог.ДобавитьСпособВывода(Аппендер);

// Теперь сообщения этого лога отправляются в OpenTelemetry
Лог.Информация("Сообщение отправляется в OTel");

ОтелАвтоконфигурация

Модуль автоматической конфигурации SDK на основе переменных окружения и YAML-файла.

Описание

Реализует спецификацию OpenTelemetry SDK Environment Variable Specification. Читает конфигурацию из переменных окружения или YAML-файла (при установленной OTEL_CONFIG_FILE).

Основная точка входа — функция Инициализировать().

Поддерживаемые переменные окружения

Переменная	Описание
`OTEL_CONFIG_FILE`	Путь к YAML-файлу конфигурации
`OTEL_SERVICE_NAME`	Имя сервиса (атрибут ресурса)
`OTEL_RESOURCE_ATTRIBUTES`	Атрибуты ресурса в формате `key=val,key2=val2` (percent-encoding; при ошибке разбора — элемент не в формате `ключ=значение`, пустой ключ, некорректный percent-encoding — значение игнорируется целиком)
`OTEL_EXPORTER_OTLP_ENDPOINT`	Адрес OTLP-экспортера
`OTEL_EXPORTER_OTLP_PROTOCOL`	Протокол (`grpc`, `http/protobuf`)
`OTEL_TRACES_SAMPLER`	Стратегия семплирования (`always_on`, `always_off`, `traceidratio`, `parentbased_always_on`, `parentbased_always_off`, `parentbased_traceidratio`)
`OTEL_TRACES_SAMPLER_ARG`	Аргумент семплера (доля для `traceidratio`)
`OTEL_PROPAGATORS`	Пропагаторы через запятую (`tracecontext`, `baggage`, `b3`, `b3multi`, `none`); для `b3` и `b3multi` нужен пакет `opentelemetry-propagator-b3` (см. СоздатьПропагаторы)
`OTEL_SDK_DISABLED`	Отключить SDK (`true`/`false`)

OTEL_LOG_LEVEL не поддерживается: спецификация не обязывает SDK поддерживать переменные окружения. Внутренние сообщения SDK пишутся в логгеры logos с именами oscript.lib.opentelemetry.*, их уровень задаётся настройками logos, например LOGOS_CONFIG=logger.oscript.lib.opentelemetry=DEBUG.

Функции

Инициализировать

Главная функция инициализации. Конфигурирует SDK по переменным окружения (или YAML-файлу), регистрирует провайдеры в ОтелГлобальный и возвращает готовый SDK.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`Произвольный`	`Неопределено`	Менеджер параметров; если не указан — создаётся по умолчанию
`ДетекторыРесурса`	`Массив`, `ФиксированныйМассив` из ИнтерфейсДетекторРесурса	`Неопределено`	Дополнительные детекторы ресурса; порядок слияния — в `СоздатьРесурс`

Возвращает: ОтелSdk — инициализированный объект SDK

Ресурс провайдеров собирает СоздатьРесурс(МенеджерПараметров, ДетекторыРесурса). При otel.sdk.disabled детекторы не вызываются: SDK ничего не экспортирует. При файловой конфигурации (OTEL_CONFIG_FILE) SDK строится только из файла: переданные детекторы не применяются, а в лог oscript.lib.opentelemetry.config пишется предупреждение.

СоздатьМенеджерПараметровПоУмолчанию

Создаёт менеджер параметров, читающий конфигурацию из переменных окружения.

Возвращает: МенеджерПараметров — объект для передачи в Инициализировать()

СоздатьРесурс

Создаёт ресурс из параметров конфигурации.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	`Неопределено`	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения
`ДетекторыРесурса`	`Массив`, `ФиксированныйМассив` из ИнтерфейсДетекторРесурса	`Неопределено`	Дополнительные детекторы ресурса

Возвращает: ОтелРесурс

Порядок слияния, каждый следующий важнее:

ОтелРесурсы.ПоУмолчанию — service.name и telemetry.sdk.*;
ОтелРесурсы.ДетекторыПоУмолчанию;
ДетекторыРесурса в порядке коллекции;
переменные окружения OTEL_RESOURCE_ATTRIBUTES и OTEL_SERVICE_NAME;
otel.resource.attributes и otel.service.name менеджера параметров.

Атрибут из конфигурации перекрывает атрибут детектора, как в Java SDK: там EnvironmentResourceProvider идёт после остальных провайдеров ресурса.

Свой ресурс сливают поверх результата: СоздатьРесурс(МенеджерПараметров).Слить(МойРесурс). Атрибуты своего ресурса важнее атрибутов конфигурации.

СоздатьТранспорт

Создаёт транспорт для экспортеров на основе параметров конфигурации.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	`Неопределено`	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения

Возвращает: транспортный объект для экспортера

СоздатьТранспортДляСигнала

Создаёт транспорт OTLP для одного сигнала — так автоконфигурация создаёт транспорты экспортеров спанов, логов и метрик. Переменные сигнала OTEL_EXPORTER_OTLP_<СИГНАЛ>_* (TRACES, LOGS, METRICS) перекрывают общие OTEL_EXPORTER_OTLP_*; нераспознанный протокол или сжатие сигнала и некорректный таймаут сигнала считаются незаданными.

Протокол (..._PROTOCOL): grpc — ОтелGrpcТранспорт; http/protobuf (по умолчанию) или http/json — ОтелHttpТранспорт.
Адрес: OTEL_EXPORTER_OTLP_<СИГНАЛ>_ENDPOINT для HTTP используется как есть (адресу без пути добавляется /), ПутьСигнала — пустая строка; для gRPC это адрес соединения, ПутьСигнала — /v1/<сигнал>. Без него берётся OTEL_EXPORTER_OTLP_ENDPOINT (по умолчанию http://localhost:4318, для gRPC http://localhost:4317), ПутьСигнала — /v1/<сигнал>. Допустимы схемы http и https: адресу HTTP без схемы добавляется http://, адрес gRPC без схемы используется как есть; с другой схемой транспорт не создаётся, ошибка пишется в лог.
Заголовки (..._HEADERS), сжатие (..._COMPRESSION: gzip или none), таймаут (..._TIMEOUT, по умолчанию 10000 мс) и TLS (..._CERTIFICATE, ..._CLIENT_KEY, ..._CLIENT_CERTIFICATE, ..._INSECURE) — значение сигнала, иначе общее. Сжатие клиент OPI_GRPC не поддерживает: для grpc выводится предупреждение, данные отправляются без сжатия.

Экспортеры автоконфигурации получают транспорт с признаком НовыйЗакрыватьТранспорт = Истина и закрывают его вместе с собой.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	—	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения
`Сигнал`	`Строка`	—	`"traces"`, `"logs"` или `"metrics"`

Возвращает: Структура — поля Транспорт (ОтелHttpТранспорт, ОтелGrpcТранспорт; Неопределено, если схема адреса не поддерживается), ПутьСигнала (Строка — путь для конструктора экспортера) и ТаймаутМс (Число — таймаут экспорта в миллисекундах; 0, если транспорт не создан)

СоздатьПровайдерТрассировки

Создаёт и конфигурирует провайдер трассировки.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	`Неопределено`	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения

Возвращает: ОтелПровайдерТрассировки

СоздатьПровайдерЛогирования

Создаёт и конфигурирует провайдер логирования. Первый процессор — ОтелПроцессорСобытийВСобытияСпана, если он не выключен ключом otel.oscript.event.to.span.event.bridge.enabled=false; за ним — пакетный процессор экспорта, если экспортер логов не none и транспорт доступен.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	`Неопределено`	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения

Возвращает: провайдер логирования

СоздатьПровайдерМетрик

Создаёт и конфигурирует провайдер метрик.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	`Неопределено`	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения

Возвращает: провайдер метрик

СоздатьПропагаторы

Создаёт пропагаторы по OTEL_PROPAGATORS (по умолчанию tracecontext,baggage): имена через запятую, без учёта регистра и пробелов по краям, повторы пропускаются. Пропагатор по имени создаёт ОтелКонфигурационнаяФабрика — так же, как для секции propagator файла конфигурации:

tracecontext — ОтелW3CПропагатор;
baggage — ОтелW3CBaggageПропагатор;
b3, b3multi — ОтелB3Пропагатор в формате single header или multi header. Класса нет в SDK: фабрика создаёт его по имени класса (Новый("ОтелB3Пропагатор", ...) с параметром "single" или "multi"), и он доступен, если установлен пакет opentelemetry-propagator-b3 и приложение подключает его (#Использовать opentelemetry-propagator-b3). Без пакета пропагатор пропускается с предупреждением в логе;
none — ОтелНоопПропагатор: пропагация отключена, остальные значения списка игнорируются с предупреждением в логе.

Неизвестное имя пропускается с предупреждением в логе. Инициализировать() передаёт результат в SDK, в том числе при OTEL_SDK_DISABLED=true.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	`Неопределено`	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения

Возвращает: ОтелКомпозитныйПропагатор, ОтелНоопПропагатор — композитный пропагатор из распознанных (пустой, если ни одно имя не распознано); ОтелНоопПропагатор — для none

СоздатьЛимитыСпана

Создаёт ОтелЛимитыСпана — с ними автоконфигурация создаёт провайдер трассировки:

количество атрибутов — OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT, иначе OTEL_ATTRIBUTE_COUNT_LIMIT, иначе 128;
длина значения атрибута — OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT, иначе OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT, иначе без ограничения;
количество событий, линков, атрибутов события и атрибутов линка — OTEL_SPAN_EVENT_COUNT_LIMIT, OTEL_SPAN_LINK_COUNT_LIMIT, OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT, OTEL_LINK_ATTRIBUTE_COUNT_LIMIT, по умолчанию 128.

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

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	`Неопределено`	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения

Возвращает: ОтелЛимитыСпана — лимиты спана

СоздатьЛимитыЗаписейЛога

Создаёт ОтелЛимитыЗаписейЛога — с ними автоконфигурация создаёт провайдер логирования:

количество атрибутов — OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT, иначе OTEL_ATTRIBUTE_COUNT_LIMIT, иначе 128;
длина значения атрибута — OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT, иначе OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT, иначе без ограничения.

Параметр	Тип	По умолчанию	Описание
`МенеджерПараметров`	`МенеджерПараметров`, `Неопределено`	`Неопределено`	Менеджер параметров; `Неопределено` — менеджер, сохранённый `Инициализировать()`, а если его нет — новый менеджер из переменных окружения

Возвращает: ОтелЛимитыЗаписейЛога — лимиты записей лога

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

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

РазобратьПарыКлючЗначение — разбирает строку key1=value1,key2=value2 (значение OTEL_EXPORTER_OTLP_HEADERS), вызывает ОтелКонфигурационнаяФабрика.РазобратьПарыКлючЗначение;
РазобратьСхемуURL — проверяет схему адреса OTLP: http и https допустимы, к адресу без схемы добавляется http://, для другой схемы возвращает Неопределено и пишет ошибку в лог.

Пример

bsl

// Минимальная инициализация по переменным окружения
// (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT должны быть установлены)
Сдк = ОтелАвтоконфигурация.Инициализировать();

Трассировщик = Сдк.ПолучитьТрассировщик("мой-сервис");

// Ресурс из конфигурации со своими атрибутами поверх
МенеджерПараметров = ОтелАвтоконфигурация.СоздатьМенеджерПараметровПоУмолчанию();
ПользовательскийРесурс = Новый ОтелПостроительРесурса()
    .Установить("deployment.environment.name", "production")
    .Построить();
ИтоговыйРесурс = ОтелАвтоконфигурация.СоздатьРесурс(МенеджерПараметров).Слить(ПользовательскийРесурс);

// Свой экспортер спанов с транспортом по переменным OTEL_EXPORTER_OTLP_*
Данные = ОтелАвтоконфигурация.СоздатьТранспортДляСигнала(МенеджерПараметров, "traces");
Если Данные.Транспорт <> Неопределено Тогда
    Экспортер = Новый ОтелЭкспортерСпанов(Данные.Транспорт, Данные.ПутьСигнала, Данные.ТаймаутМс, Истина);
КонецЕсли;

// При завершении работы
Сдк.Закрыть(30000);

YAML-конфигурация

Если в менеджере параметров задан ключ otel.config.file (переменная OTEL_CONFIG_FILE), Инициализировать читает файл декларативной конфигурации. Менеджер — переданный или, без МенеджерПараметров, менеджер из переменных окружения; в менеджер с провайдером переменных окружения OTEL_CONFIG_FILE попадает как otel.config.file. Формат описан в ОтелФайловаяКонфигурация, поле file_format обязательно, остальные параметры otel.* менеджера и переменные OTEL_* не применяются. Устаревший ключ otel.experimental.config.file (OTEL_EXPERIMENTAL_CONFIG_FILE) читается, если otel.config.file не задан, и пишет предупреждение в лог:

yaml

file_format: "1.0"

resource:
  attributes:
    - name: service.name
      value: мой-сервис

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/traces
  sampler:
    parent_based:
      root:
        trace_id_ratio_based:
          ratio: 0.1

propagator:
  composite_list: tracecontext,baggage

См. также

ОтелКонфигурационнаяФабрика

Модуль создания SDK по модели файла конфигурации.

Описание

Строит ОтелSdk по модели ОтелКонфигурация, которую возвращает ОтелФайловаяКонфигурация.Разобрать. Аналог Java SDK: OpenTelemetryConfigurationFactory. ОтелАвтоконфигурация.Инициализировать() при заданном в менеджере параметров ключе otel.config.file (переменной OTEL_CONFIG_FILE) создаёт SDK функцией Создать и регистрирует его в ОтелГлобальный; сама фабрика SDK глобально не регистрирует.

Что строит Создать по секциям файла:

disabled: true — SDK, который не экспортирует телеметрию, остальные секции не читаются: провайдер трассировки с сэмплером ВсегдаВыключен (спаны не записываются), провайдеры логирования и метрик без процессоров и читателей, ресурс с атрибутами по умолчанию (как СоздатьРесурс() без секции resource). Пропагаторы не задаются: Сдк.Пропагаторы() возвращает ОтелНоопПропагатор;
resource — ресурс, общий для всех провайдеров (см. СоздатьРесурс);
tracer_provider, logger_provider, meter_provider — провайдеры сигналов (СоздатьПровайдерТрассировки, СоздатьПровайдерЛогирования, СоздатьПровайдерМетрик). Провайдер создаётся, только если секция есть в файле. Без секции SDK получает no-op провайдер этого сигнала (см. ОтелSdk), как требует схема файла;
attribute_limits — общие лимиты атрибутов спанов и записей логов; как они сочетаются с limits провайдера, см. СоздатьПровайдерТрассировки и СоздатьПровайдерЛогирования;
propagator — пропагаторы SDK (см. СоздатьПропагаторы); без секции — ОтелНоопПропагатор.

log_level (уровень внутреннего логгера SDK) не поддерживается: ключ проходит проверку по схеме, но на SDK не влияет. Внутренние логи SDK пишутся логгерами logos с именами oscript.lib.opentelemetry.*, и их уровень задаётся настройками logos — в logos.cfg рядом со стартовым сценарием или в переменной LOGOS_CONFIG: настройка узла иерархии действует на все логгеры SDK, rootLogger — на все логгеры процесса. Без настроек logos уровень — INFO, как у log_level по умолчанию.

logger.oscript.lib.opentelemetry=DEBUG

Проверка модели. До создания компонентов Создать проверяет модель по схеме файла конфигурации по тем же правилам, по которым Разобрать проверяет файл (см. ОтелФайловаяКонфигурация.ПроверитьМодель): типы значений, обязательные свойства, допустимые значения перечислений и границы чисел. Так проверяется и модель, собранная в коде: спецификация Configuration SDK (Create) требует ошибку на значении, недопустимом по схеме. Ошибка перечисляет все нарушения с путём свойства схемы, например /tracer_provider/processors/0/batch/schedule_delay: Значение -1 меньше минимума 0. Модель проверяется и при disabled: true, как файл при разборе. По схеме у провайдера трассировки и логирования обязателен хотя бы один процессор (processors), у провайдера метрик — хотя бы один читатель (readers): провайдер без них — ошибка.

Значение null. Свойство со значением null получает значение по умолчанию (Configuration SDK, Create). В модели из кода null — Неопределено: фабрика строит SDK по копии модели, в которой такое поле получает значение нового объекта того же класса, например Интервал = Неопределено у читателя — 60000 мс. ЗадержкаОтправки = Неопределено пакетного процессора — 5000 мс у спанов и 1000 мс у записей лога. Модель, переданная фабрике, не меняется.

Экспортеры процессоров и читателей отправляют данные по OTLP или выводят их в консоль:

otlp_http — фабрика создаёт ОтелHttpТранспорт с протоколом http/protobuf, при encoding: json — http/json. Адрес endpoint — URL со схемой http или https, используется как есть, включая путь (по умолчанию http://localhost:4318/v1/<сигнал>); compression: gzip включает сжатие;
otlp_grpc — фабрика создаёт ОтелGrpcТранспорт. endpoint — адрес коллектора без пути (по умолчанию http://localhost:4317): URL со схемой http или https или адрес без схемы, соединение с которым идёт по TLS; сервис сигнала транспорт выбирает сам. Сжатие клиент OPI_GRPC не поддерживает (OpenIntegrations#112): при compression: gzip фабрика пишет предупреждение в лог, данные отправляются без сжатия. Ответ клиент принимает не больше 4 MiB, другой лимит задать нельзя (OpenIntegrations#113): при max_response_size не 4194304 фабрика пишет предупреждение в лог;
console — фабрика создаёт ОтелКонсольныйТранспорт: каждый экспорт выводится в стандартный вывод одной строкой OTLP JSON, срок экспорта — 10000 мс. У экспортера метрик действуют temporality_preference и default_histogram_aggregation.

У обоих экспортеров max_request_size — наибольший размер запроса до сжатия в байтах (по умолчанию 64 MiB, 0 — без ограничения): запрос больше лимита не отправляется; max_response_size у otlp_http — наибольший размер ответа (по умолчанию 4 MiB): экспорт с ответом больше лимита неуспешен.

У обоих экспортеров timeout — срок каждого экспорта в миллисекундах вместе с повторами и таймаут запроса (по умолчанию 10000, 0 — без ограничения); заголовки (у gRPC — метаданные вызова) берутся из headers и headers_list, при совпадении имён действует headers, а заголовок headers со значением null пропускается, как требует схема файла.

Значения по описанию свойств. Схема описывает часть ограничений только текстом (description), а спецификация Configuration SDK (Create) требует ошибку и на значении, недопустимом по такому описанию. Фабрика выбрасывает исключение, если:

значение атрибута ресурса не соответствует его type (без type — string): например, число у атрибута без type или дробное число у int; атрибут со значением null пропускается;
attributes_list или headers_list не разбирается в формате переменной окружения (OTEL_RESOURCE_ATTRIBUTES, OTEL_EXPORTER_OTLP_HEADERS): элемент не в формате ключ=значение, пустой ключ, некорректный percent-encoding;
compression — не gzip и не none: другие алгоритмы SDK не поддерживает;
у endpoint схема не http и не https (у otlp_http адрес без схемы — тоже ошибка);
в tls задан только один из key_file и cert_file, или ca_file, key_file, cert_file — не абсолютный путь или путь к файлу, которого нет.

tls фабрика передаёт транспорту. HTTP-клиент OneScript файлы сертификатов не применяет и сертификат сервера по HTTPS не проверяет: транспорт пишет об этом предупреждение в лог. gRPC-транспорт проверяет сертификат сервера по ca_file, а insecure: true у адреса без схемы — соединение без TLS; клиентский ключ и сертификат (mTLS) клиент OPI_GRPC не поддерживает (OpenIntegrations#102), транспорт пишет предупреждение в лог.

Транспорт создан фабрикой, поэтому экспортер закрывает его вместе с собой: Сдк.Закрыть() закрывает провайдеры, их процессоры и читатели, экспортеры и транспорты. Пакетные процессоры и периодические читатели запускают фоновый экспорт сразу при создании. Таймаут Сдк.Закрыть() без параметра — 30000 мс.

Компоненты, которых нет в SDK. Экспортер, процессор, pull-экспортер, продюсер метрик, сэмплер, пропагатор или генератор ID, которых нет в SDK, разбор файла сохраняет как ОтелКонфигурацияКомпонента — имя и свойства. Фабрика создаёт такой компонент провайдером компонента (PluginComponentProvider), который приложение зарегистрировало с типом и именем компонента (см. ЗарегистрироватьПровайдерКомпонента). Провайдер получает свойства компонента из файла как ОтелСвойстваКонфигурации и возвращает компонент. Без провайдера фабрика выбрасывает исключение с видом и именем компонента, например Экспортер спанов "my_exporter" не поддерживается. Поддерживаются: otlp_http, otlp_grpc, console. Так требует спецификация Configuration SDK (Create): конфигурация с ошибкой не должна давать работающий SDK, который молча не делает того, что задано в файле. Исключение провайдера фабрика передаёт вызывающему. В SDK есть:

Компонент	Встроенные	Тип провайдера компонента
Экспортер спанов	`otlp_http`, `otlp_grpc`, `console`	`ОтелТипКомпонентаКонфигурации.ЭкспортерСпанов()`
Экспортер записей лога	`otlp_http`, `otlp_grpc`, `console`	`ОтелТипКомпонентаКонфигурации.ЭкспортерЗаписейЛога()`
Экспортер метрик периодического читателя	`otlp_http`, `otlp_grpc`, `console`	`ОтелТипКомпонентаКонфигурации.ЭкспортерМетрик()`
Процессор спанов	`batch`, `simple`	`ОтелТипКомпонентаКонфигурации.ПроцессорСпанов()`
Процессор записей лога	`batch`, `simple`, `event_to_span_event_bridge/development`	`ОтелТипКомпонентаКонфигурации.ПроцессорЗаписейЛога()`
Pull-экспортер (читатель `pull`)	нет	`ОтелТипКомпонентаКонфигурации.ЧитательМетрикPull()`
Продюсер метрик	нет	`ОтелТипКомпонентаКонфигурации.ПродюсерМетрик()`
Сэмплер	`always_on`, `always_off`, `trace_id_ratio_based`, `parent_based`, `always_record`	`ОтелТипКомпонентаКонфигурации.Сэмплер()`
Пропагатор	`tracecontext`, `baggage`, `b3`, `b3multi` (пакет `opentelemetry-propagator-b3`), `none`	`ОтелТипКомпонентаКонфигурации.Пропагатор()`
Генератор ID	`random`	`ОтелТипКомпонентаКонфигурации.ГенераторИд()`

Встроенный компонент создаётся без провайдера, даже если провайдер с тем же именем зарегистрирован. Провайдер pull-экспортера возвращает читатель метрик, например ОтелПрометеусЧитательМетрик: фабрика добавляет ему продюсеры секции pull (ДобавитьПродюсер) и, если задан cardinality_limits, лимиты мощности видов инструментов (УстановитьЛимитМощностиДляВида; вид без своего лимита получает default). Пропагатор из строки composite_list провайдер ищется по имени, как оно записано в строке; свойств у него нет.

Процессоры и читатели, которые функция успела создать до ошибки, закрываются вместе с фоновым экспортом и транспортами.

Функции СоздатьРесурс, СоздатьПровайдерТрассировки, СоздатьПровайдерЛогирования, СоздатьПровайдерМетрик и СоздатьПропагаторы строят по одной части SDK из части модели и проверяют эту часть по схеме, как Создать всю модель: путь в ошибке — путь части в модели, например /tracer_provider/.... Признак disabled учитывает только Создать.

Функции

Создать

Создаёт SDK по модели файла конфигурации (см. «Описание»). Выбрасывает исключение, если:

не задан ФорматФайла (file_format) или его версия не 1.x — по тем же правилам, что при разборе файла;
модель не соответствует схеме (см. «Проверка модели»), в том числе нет обязательного свойства: экспортера процессора или читателя, root у always_record, процессоров провайдера трассировки или логирования, читателей провайдера метрик (Configuration SDK, Create: обязательное свойство, которого нет в модели, — ошибка);
значение недопустимо по описанию свойства (см. «Значения по описанию свойств»);
в модели есть компонент, которого нет в SDK, и для него не зарегистрирован провайдер компонента;
провайдер компонента выбросил исключение в СоздатьКомпонент — исключение передаётся как есть;
в секции propagator значение none указано вместе с другими пропагаторами.

При исключении функция закрывает провайдеры, которые успела создать: их фоновый экспорт и транспорты не остаются работать.

Параметр	Тип	По умолчанию	Описание
`Модель`	`ОтелКонфигурация`	—	Модель файла конфигурации из `ОтелФайловаяКонфигурация.Разобрать`

Возвращает: ОтелSdk — настроенный SDK; глобально не зарегистрирован

СоздатьРесурс

Создаёт ресурс по секции resource. Основа — ресурс с атрибутами по умолчанию (service.name = unknown_service:oscript, telemetry.sdk.*, атрибуты детекторов хоста, процесса и процессора). Переменные OTEL_SERVICE_NAME и OTEL_RESOURCE_ATTRIBUTES не читаются: при файловой конфигурации их значения попадают в ресурс только через подстановку ${...} в файле. Поверх основы применяются:

attributes_list — строка в формате OTEL_RESOURCE_ATTRIBUTES (key1=value1,key2=value2, percent-encoding). Строка, которую не удалось разобрать (элемент не в формате ключ=значение, пустой ключ, некорректный percent-encoding), — исключение: у переменной окружения такое значение отбрасывается с записью в лог, а для конфигурации Configuration SDK требует ошибку;
attributes — список атрибутов; он важнее attributes_list при совпадении ключей. Значение атрибута должно соответствовать его type (без type — string), иначе исключение; атрибут со значением null пропускается.

schema_url задаёт URL схемы ресурса; без него ресурс получает схему детекторов, если она есть.

Параметр	Тип	По умолчанию	Описание
`КонфигРесурса`	`ОтелКонфигурацияРесурса`, `Неопределено`	`Неопределено`	Секция `resource` (`Модель.Ресурс`); `Неопределено` — ресурс по умолчанию

Возвращает: ОтелРесурс — ресурс

СоздатьПровайдерТрассировки

Создаёт ОтелПровайдерТрассировки по секции tracer_provider:

процессоры — для каждого batch с экспортером ОтелПакетныйПроцессорСпанов с параметрами schedule_delay, export_timeout, max_queue_size, max_export_batch_size, для каждого simple — ОтелПростойПроцессорСпанов, который экспортирует спан сразу при завершении; экспортер у процессора обязателен — процессор без него исключение. Несколько процессоров объединяются в ОтелКомпозитныйПроцессорСпанов;
сэмплер — always_on, always_off, trace_id_ratio_based (доля ratio), parent_based с корневым сэмплером root и сэмплерами для родителей remote_parent_sampled, remote_parent_not_sampled, local_parent_sampled, local_parent_not_sampled или always_record с обёрнутым сэмплером root, см. ОтелСэмплер. Вложенные сэмплеры создаются так же, как сэмплер провайдера, каждый со своими параметрами (например, своей долей ratio), и сами могут быть parent_based или always_record. Без сэмплера — parent_based с корневым always_on; незаданные вложенные сэмплеры parent_based — значения по умолчанию: root и сэмплеры для сэмплированного родителя — always_on, для несэмплированного — always_off. У always_record сэмплер root обязателен: без него выбрасывается исключение. Сэмплер, которого нет в SDK, в том числе вложенный, — исключение;
генератор ID — id_generator: random и секция без генератора — генератор SDK по умолчанию, другой генератор — исключение;
лимиты спана — из limits провайдера. Количество атрибутов — из limits, если задано, иначе из attribute_limits, иначе 128; длина значения атрибута — из limits, если задана, иначе из attribute_limits, иначе без ограничения; глубина значения атрибута — так же, иначе 64.

Параметр	Тип	По умолчанию	Описание
`Ресурс`	ОтелРесурс	—	Ресурс провайдера
`КонфигПровайдера`	`ОтелКонфигурацияПровайдераТрассировки`	—	Секция `tracer_provider` (`Модель.ПровайдерТрассировки`)
`КонфигГлобЛимитов`	`ОтелКонфигурацияЛимитовАтрибутов`, `Неопределено`	`Неопределено`	Секция `attribute_limits` (`Модель.ЛимитыАтрибутов`)

Возвращает: ОтелПровайдерТрассировки — провайдер трассировки

СоздатьПровайдерЛогирования

Создаёт ОтелПровайдерЛогирования по секции logger_provider. Процессоры — для каждого batch с экспортером ОтелПакетныйПроцессорЛогов (параметры те же, что у процессора спанов), для каждого simple — ОтелПростойПроцессорЛогов, который экспортирует запись сразу; экспортер у процессора обязателен — процессор без него исключение. Для event_to_span_event_bridge/development — ОтелПроцессорСобытийВСобытияСпана: в файловой конфигурации он есть, только если задан в списке, и переносит события в спан для процессоров после него. Несколько процессоров объединяются в ОтелКомпозитныйПроцессорЛогов. Лимиты записей лога: количество атрибутов — из limits провайдера, если задано, иначе из attribute_limits, иначе 128; длина значения — из limits, если задана, иначе из attribute_limits, иначе без ограничения; глубина значения — так же, иначе 64.

Параметр	Тип	По умолчанию	Описание
`Ресурс`	ОтелРесурс	—	Ресурс провайдера
`КонфигПровайдера`	`ОтелКонфигурацияПровайдераЛогирования`	—	Секция `logger_provider` (`Модель.ПровайдерЛогирования`)
`КонфигГлобЛимитов`	`ОтелКонфигурацияЛимитовАтрибутов`, `Неопределено`	`Неопределено`	Секция `attribute_limits` (`Модель.ЛимитыАтрибутов`)

Возвращает: ОтелПровайдерЛогирования — провайдер логирования

СоздатьПровайдерМетрик

Создаёт ОтелПровайдерМетрик по секции meter_provider:

читатели — для каждого periodicОтелПериодическийЧитательМетрик с интервалом interval и таймаутом экспорта timeout и экспортером otlp_http или otlp_grpc; экспортер обязателен — читатель без него исключение. Читатель pull и продюсеры producers — исключение: встроенных pull-экспортеров и продюсеров в SDK нет. Временная агрегация — из temporality_preference экспортера: cumulative (по умолчанию), delta или low_memory; агрегацию гистограмм по умолчанию (default_histogram_aggregation: explicit_bucket_histogram по умолчанию или base2_exponential_bucket_histogram) читатель берёт у экспортера. Лимит мощности вида инструмента — из cardinality_limits: лимит вида (counter, histogram, ...), иначе default, иначе 2000;
фильтр exemplars — exemplar_filter: trace_based (по умолчанию), always_on или always_off;
представления — для каждого элемента viewsОтелСелекторИнструментов по selector и ОтелПредставление по stream, зарегистрированные в провайдере до выдачи метров. Тип инструмента counter, up_down_counter, histogram, gauge, observable_counter, observable_up_down_counter, observable_gauge — вид Counter, UpDownCounter, Histogram, Gauge, ObservableCounter, ObservableUpDownCounter, ObservableGauge. Агрегация — функция ОтелАгрегация: explicit_bucket_histogram — ГистограммаСЯвнымиГраницами(boundaries, record_min_max), base2_exponential_bucket_histogram — ГистограммаЭкспоненциальная(max_size, max_scale, record_min_max), default, drop, sum, last_value — агрегации с этими именами. attribute_keys.included и excluded — разрешённые и исключённые ключи атрибутов, ключ может быть шаблоном с * и ?.

Другое значение перечисления, в том числе в другом регистре, не проходит проверку модели.

Параметр	Тип	По умолчанию	Описание
`Ресурс`	ОтелРесурс	—	Ресурс провайдера
`КонфигПровайдера`	`ОтелКонфигурацияПровайдераМетрик`	—	Секция `meter_provider` (`Модель.ПровайдерМетрик`)

Возвращает: ОтелПровайдерМетрик — провайдер метрик

СоздатьПропагаторы

Создаёт пропагаторы по секции propagator. Имена берутся из списка composite (ключи элементов, регистр учитывается, как в ключах схемы), затем из строки composite_list (через запятую, как в OTEL_PROPAGATORS: регистр и пробелы по краям не учитываются); повторы пропускаются.

tracecontext — ОтелW3CПропагатор;
baggage — ОтелW3CBaggageПропагатор;
b3, b3multi — ОтелB3Пропагатор в формате single header или multi header. Класса нет в SDK: фабрика создаёт его по имени класса (Новый("ОтелB3Пропагатор", ...) с параметром "single" или "multi"), и он доступен, если установлен пакет opentelemetry-propagator-b3 и приложение подключает его (#Использовать opentelemetry-propagator-b3). Без пакета функция выбрасывает исключение с подсказкой, как установить пакет;
none — отключает пропагацию: ОтелНоопПропагатор. Вместе с другими пропагаторами none указывать нельзя — функция выбрасывает исключение.

Пропагатор, которого нет в SDK (например, xray), — исключение.

Параметр	Тип	По умолчанию	Описание
`КонфигПропагатора`	`ОтелКонфигурацияПропагатора`, `Неопределено`	`Неопределено`	Секция `propagator` (`Модель.Пропагатор`)

Возвращает: ОтелКомпозитныйПропагатор, ОтелНоопПропагатор — композитный пропагатор; ОтелНоопПропагатор, если секции нет, в ней не задано ни одного пропагатора или задан none

Процедуры

ЗарегистрироватьПровайдерКомпонента

Регистрирует провайдер компонента (Configuration SDK, Register PluginComponentProvider). Когда в модели встречается компонент, которого нет в SDK, Создать и функции частей ищут провайдер по типу и имени компонента и вызывают его функцию СоздатьКомпонент(Свойства) — Create Component спецификации. Свойства — ОтелСвойстваКонфигурации со свойствами компонента из файла; компонент без свойств (my_exporter:) даёт пустые свойства. Провайдер возвращает компонент типа, под которым зарегистрирован, например экспортер спанов. Если свойства не подходят, СоздатьКомпонент выбрасывает исключение, и фабрика передаёт его из Создать. Значение не того типа геттер ОтелСвойстваКонфигурации отклоняет исключением сам; обязательные свойства проверяет провайдер.

Реестр общий для процесса: регистрируйте провайдеры при запуске приложения, до Создать или ОтелАвтоконфигурация.Инициализировать(). Тип и имя — уникальный ключ: повторная регистрация с теми же типом и именем выбрасывает исключение Провайдер компонента <Тип> "<Имя>" уже зарегистрирован. Одно имя можно зарегистрировать для разных типов.

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

Пример провайдера экспортера спанов my_exporter (класс МойПровайдерЭкспортера):

bsl

// Свойства - ОтелСвойстваКонфигурации - свойства my_exporter из файла
Функция СоздатьКомпонент(Свойства) Экспорт
    // Нет ключа - Неопределено, endpoint: без значения - Null
    Адрес = Свойства.ПолучитьСтроку("endpoint");
    Если Адрес = Неопределено Или Адрес = Null Тогда
        ВызватьИсключение "my_exporter: не задано обязательное свойство endpoint";
    КонецЕсли;
    Возврат Новый МойЭкспортерСпанов(Адрес, Свойства.ПолучитьЦелое("timeout", 10000));
КонецФункции

bsl

ОтелКонфигурационнаяФабрика.ЗарегистрироватьПровайдерКомпонента(
    Новый МойПровайдерЭкспортера(), ОтелТипКомпонентаКонфигурации.ЭкспортерСпанов(), "my_exporter");
Сдк = ОтелКонфигурационнаяФабрика.Создать(ОтелФайловаяКонфигурация.Разобрать("/etc/otel/config.yaml"));

yaml

tracer_provider:
  processors:
    - batch:
        exporter:
          my_exporter:
            endpoint: http://collector:9000
            timeout: 5000

Опишите в документации провайдера схему конфигурации компонента и приведите пример, как выше: свойства, их типы, обязательные свойства и значения по умолчанию (Configuration SDK, Create Component). Для my_exporter:

Свойство	Тип	Обязательное	По умолчанию	Описание
`endpoint`	string	да	—	Адрес приёмника спанов
`timeout`	integer	нет	`10000`	Срок экспорта, мс

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

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

РазрешитьПропагаторПоИмени — создаёт пропагатор по имени tracecontext, baggage, b3 или b3multi для OTEL_PROPAGATORS (ОтелАвтоконфигурация.СоздатьПропагаторы): неизвестное имя и b3 без пакета пропускаются с предупреждением в логе, а не дают исключение, как в файле конфигурации;
РазобратьПарыКлючЗначение — разбирает строку key1=value1,key2=value2 (заголовки OTEL_EXPORTER_OTLP_HEADERS): элементы без ключа пропускаются, некорректный percent-encoding остаётся как есть. headers_list файла конфигурации фабрика разбирает строго: ошибка разбора — исключение;
РазобратьАтрибутыРесурса — строгий разбор attributes_list и OTEL_RESOURCE_ATTRIBUTES: при ошибке выбрасывает исключение.

Пример

bsl

#Использовать opentelemetry

Модель = ОтелФайловаяКонфигурация.Разобрать("/etc/otel/config.yaml");

// SDK по всему файлу. Фабрика не регистрирует SDK глобально
Сдк = ОтелКонфигурационнаяФабрика.Создать(Модель);
ОтелГлобальный.Установить(Сдк);

Трассировщик = ОтелГлобальный.ПолучитьТрассировщик("мой-сервис");
// ...

// При завершении работы закрываются провайдеры, процессоры, экспортеры и их транспорты
Сдк.Закрыть();

bsl

// Другой вариант: только провайдер трассировки по секциям resource, tracer_provider
// и attribute_limits
Модель = ОтелФайловаяКонфигурация.Разобрать("/etc/otel/config.yaml");
Если Модель.ПровайдерТрассировки <> Неопределено Тогда
    Ресурс = ОтелКонфигурационнаяФабрика.СоздатьРесурс(Модель.Ресурс);
    Провайдер = ОтелКонфигурационнаяФабрика.СоздатьПровайдерТрассировки(
        Ресурс, Модель.ПровайдерТрассировки, Модель.ЛимитыАтрибутов);
    ОтелГлобальный.УстановитьПровайдерТрассировки(Провайдер);
    // ...
    Провайдер.Закрыть();
КонецЕсли;

См. также

ОтелКонфигурация

Модель файла конфигурации: объекты с настройками SDK, которые заполняет разбор файла и читает фабрика.

Описание

ОтелКонфигурация — корень модели файла конфигурации. Её поля хранят секции файла: ресурс, лимиты атрибутов, пропагатор и провайдеры сигналов. Каждая секция — объект своего класса ОтелКонфигурация..., все классы описаны в разделе «Поля». У классов модели есть только поля (экспортные переменные), методов нет.

Модель создаёт ОтелФайловаяКонфигурация.Разобрать: читает файл, подставляет переменные окружения ${...}, проверяет file_format, проверяет файл по схеме opentelemetry-configuration и заполняет поля по ключам файла. Читает модель ОтелКонфигурационнаяФабрика: Создать(Модель) строит по ней SDK, а СоздатьРесурс, СоздатьПровайдерТрассировки, СоздатьПровайдерЛогирования, СоздатьПровайдерМетрик и СоздатьПропагаторы принимают её части: Модель.Ресурс, Модель.ПровайдерТрассировки, Модель.ЛимитыАтрибутов и другие. Что фабрика строит по каждой секции, описано на её странице; здесь — поля модели, ключи файла и значения по умолчанию.

Как Разобрать заполняет поля:

ключ есть в файле — поле получает его значение. Значения уже проверены по схеме: тип, обязательные свойства и ограничения значений (например, число вместо строки или schedule_delay: -1 — исключение Разобрать с путём до свойства);
ключа нет или его значение null — поле сохраняет значение по умолчанию (колонка «По умолчанию» в таблицах);
поле секции (тип ОтелКонфигурация...) равно Неопределено, если секции нет в файле. Секция без значения (например, tracer_provider: без вложенных ключей) — ошибка схемы: секция — объект, а у tracer_provider и logger_provider обязателен непустой список processors, у meter_provider — readers. Секцию без обязательных свойств со значениями по умолчанию задаёт пустой объект: attribute_limits: {}. Компонент, для которого схема допускает null (otlp_http:, always_on:), ключом без значения задаётся с настройками по умолчанию;
поля-массивы (Атрибуты, Составной, Процессоры, Читатели, Представления, Заголовки) не бывают Неопределено: без ключа в файле это пустой массив. Процессоры, Читатели и Представления — массивы объектов модели;
компонент, которого нет в SDK (процессор, экспортер или сэмплер пользователя, pull-экспортер, продюсер метрик), разбор сохраняет как ОтелКонфигурацияКомпонента: имя и свойства как в файле, так требует спецификация Configuration SDK (Parse). Фабрика создаёт такой компонент зарегистрированным провайдером компонента, без провайдера выбрасывает исключение (см. ОтелКонфигурационнаяФабрика, «Компоненты, которых нет в SDK»). Другие ключи схемы, которых нет в таблицах (например, distribution, log_level и свойства с суффиксом /development), разбор пропускает без предупреждения. Уровень логов SDK задаётся настройками logos (см. ОтелКонфигурационнаяФабрика, «Описание»). Ключ, которого нет в схеме, — ошибка, кроме файла с более новой младшей версией file_format (см. ОтелФайловаяКонфигурация, «Проверка по схеме»).

Модель можно изменить в коде перед вызовом фабрики: фабрика читает поля в момент вызова и ничего не запоминает. Так можно, например, заменить адрес экспортера или сэмплер после разбора файла (см. «Пример»). Изменения модели после Создать построенный SDK не меняют. ОтелАвтоконфигурация.Инициализировать() по переменной OTEL_CONFIG_FILE вызывает Разобрать и Создать сама и модель не возвращает. Чтобы изменить модель, вызовите обе функции в своём коде и зарегистрируйте SDK через ОтелГлобальный.Установить.

Объекты модели можно создать и без файла, через Новый (см. «Конструктор»). Фабрика проверяет такую модель по схеме так же, как Разобрать проверяет файл (Configuration SDK, Create; см. ОтелФайловаяКонфигурация.ПроверитьМодель): без ФорматФайла или с версией не 1.x, без Экспортер у процессора или читателя, с провайдером без процессоров или читателей, с числом вне границ схемы (например, ЗадержкаОтправки = -1), значением не из перечисления или значением не того типа она выбрасывает исключение с путём свойства схемы. Модель Новый ОтелКонфигурация() с одним заполненным полем ФорматФайла = "1.0" даёт SDK с no-op провайдерами сигналов и ОтелНоопПропагатор — как файл с одним ключом file_format.

Неопределено в поле модели — значение null: фабрика берёт значение по умолчанию из колонки «По умолчанию», как требует спецификация Configuration SDK (Create) для свойства со значением null. Например, Интервал = Неопределено у периодического читателя — интервал 60000 мс. Фабрика работает с копией модели и саму модель не меняет. Поле, у которого значения по умолчанию нет (в колонке Неопределено), остаётся не заданным.

Ключи файла и поля модели:

yaml

file_format: "1.0"                    # ФорматФайла
disabled: false                       # Отключен
resource:                             # Ресурс
  attributes:                         #   Атрибуты
    - name: service.name
      value: мой-сервис
  attributes_list: env=prod           #   СписокАтрибутов
  schema_url: https://opentelemetry.io/schemas/1.26.0  #   АдресСхемы
attribute_limits:                     # ЛимитыАтрибутов
  attribute_count_limit: 64           #   МаксКоличествоАтрибутов
propagator:                           # Пропагатор
  composite:                          #   Составной
    - tracecontext:
    - baggage:
tracer_provider:                      # ПровайдерТрассировки
  processors:                         #   Процессоры
    - batch:
        schedule_delay: 5000          #     ЗадержкаОтправки
        exporter:
          otlp_http:                  #     Экспортер
            endpoint: http://localhost:4318/v1/traces   # Адрес
  limits:                             #   Лимиты
    event_count_limit: 64             #     МаксСобытий
  sampler:                            #   Сэмплер
    parent_based:                     #     Тип
      root:                           #     Корневой
        trace_id_ratio_based:         #       Тип
          ratio: 0.1                  #       Доля
meter_provider:                       # ПровайдерМетрик
  exemplar_filter: trace_based        #   ФильтрЭкземпляров
  readers:                            #   Читатели
    - periodic:
        interval: 60000               #     Интервал
        exporter:
          otlp_http:                  #     Экспортер
            endpoint: http://localhost:4318/v1/metrics
            temporality_preference: delta
  views:                              #   Представления
    - selector:                       #     Селектор
        instrument_name: http.server.duration   # ИмяИнструмента
      stream:                         #     Поток
        aggregation:                  #       Агрегация
          explicit_bucket_histogram:  #         Тип
            boundaries: [0.1, 0.5, 1] #         Границы
        attribute_keys:               #       КлючиАтрибутов
          included: [http.*]          #         Включенные
logger_provider:                      # ПровайдерЛогирования
  processors:                         #   Процессоры
    - batch:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/logs

Конструктор

bsl

Новый ОтелКонфигурация()
Новый ОтелКонфигурацияРесурса()
Новый ОтелКонфигурацияЛимитовАтрибутов()
Новый ОтелКонфигурацияПропагатора()
Новый ОтелКонфигурацияПровайдераТрассировки()
Новый ОтелКонфигурацияЛимитовСпана()
Новый ОтелКонфигурацияСэмплера()
Новый ОтелКонфигурацияПровайдераМетрик()
Новый ОтелКонфигурацияПровайдераЛогирования()
Новый ОтелКонфигурацияПакетногоПроцессора()
Новый ОтелКонфигурацияПростогоПроцессора()
Новый ОтелКонфигурацияПериодическогоЧитателя()
Новый ОтелКонфигурацияPullЧитателя()
Новый ОтелКонфигурацияЛимитовМощности()
Новый ОтелКонфигурацияПредставления()
Новый ОтелКонфигурацияСелектораИнструментов()
Новый ОтелКонфигурацияПотокаМетрики()
Новый ОтелКонфигурацияАгрегации()
Новый ОтелКонфигурацияКлючейАтрибутов()
Новый ОтелКонфигурацияЭкспортераOtlpHttp()
Новый ОтелКонфигурацияЭкспортераOtlpGrpc()
Новый ОтелКонфигурацияКонсольногоЭкспортера()
Новый ОтелКонфигурацияКомпонента()

Параметров у конструкторов нет: поля получают значения из колонки «По умолчанию». Это те же значения, что получает поле при разборе файла без своего ключа. Исключение — ЗадержкаОтправки пакетного процессора: значение по умолчанию у спанов и записей лога разное, поэтому у объекта из Новый она Неопределено и фабрика берёт 5000 мс для спанов и 1000 мс для записей лога; разбор файла без ключа сразу заполняет 5000 или 1000.

Поля

В таблицах «Ключ в файле» — ключ внутри секции, которой соответствует класс; «По умолчанию» — значение поля у нового объекта, оно же остаётся у поля, если ключа нет в файле.

ОтелКонфигурация

Весь файл. Объект возвращает ОтелФайловаяКонфигурация.Разобрать, принимает ОтелКонфигурационнаяФабрика.Создать.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`ФорматФайла`	`Строка`	`""`	`file_format`	Версия формата файла. `Разобрать` требует этот ключ и принимает только версии `1.x`. Пишите версию в кавычках: `1.0` без кавычек YAML читает как число 1, и разбор выбрасывает исключение. Обязательное поле: модель без него или с версией не `1.x` фабрика не создаёт — выбрасывает исключение
`Отключен`	`Булево`	`Ложь`	`disabled`	`Истина` — фабрика создаёт SDK, который не экспортирует телеметрию, и не читает остальные поля. Значение по схеме — булево: подстановка `${OTEL_SDK_DISABLED}` без кавычек даёт булево значение, пустая — `null` (`Ложь`), другая строка — ошибка разбора
`Ресурс`	`ОтелКонфигурацияРесурса`, `Неопределено`	`Неопределено`	`resource`	Ресурс SDK; `Неопределено` — ресурс по умолчанию
`ЛимитыАтрибутов`	`ОтелКонфигурацияЛимитовАтрибутов`, `Неопределено`	`Неопределено`	`attribute_limits`	Общие лимиты атрибутов спанов и записей логов; `Неопределено` — не заданы
`Пропагатор`	`ОтелКонфигурацияПропагатора`, `Неопределено`	`Неопределено`	`propagator`	Пропагаторы SDK; `Неопределено` — пропагация отключена (`ОтелНоопПропагатор`)
`ПровайдерТрассировки`	`ОтелКонфигурацияПровайдераТрассировки`, `Неопределено`	`Неопределено`	`tracer_provider`	Провайдер трассировки; `Неопределено` — SDK получает no-op провайдер трассировки
`ПровайдерМетрик`	`ОтелКонфигурацияПровайдераМетрик`, `Неопределено`	`Неопределено`	`meter_provider`	Провайдер метрик; `Неопределено` — SDK получает no-op провайдер метрик
`ПровайдерЛогирования`	`ОтелКонфигурацияПровайдераЛогирования`, `Неопределено`	`Неопределено`	`logger_provider`	Провайдер логирования; `Неопределено` — SDK получает no-op провайдер логирования

ОтелКонфигурацияРесурса

Секция resource, поле ОтелКонфигурация.Ресурс. Ресурс по ней создаёт ОтелКонфигурационнаяФабрика.СоздатьРесурс.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Атрибуты`	`Массив` из `Структура`	пустой массив	`attributes`	Атрибуты ресурса — структуры с полями `Имя` (`Строка`, из `name`), `Значение` (из `value` без преобразования: строка, число, булево или массив, как прочитал YAML; `value: null` — `Неопределено`) и `Тип` (из `type`: `string`, `bool`, `int`, `double`, `string_array`, `bool_array`, `int_array`, `double_array`; без `type` — `Неопределено`, тип `string`). Фабрика проверяет, что значение соответствует типу: строка, булево, целое число, число или непустой массив значений своего типа; иначе — исключение. Атрибут со значением `Неопределено` фабрика пропускает: он не перекрывает атрибут из `СписокАтрибутов`. У структуры, собранной в коде, поля `Тип` может не быть — тип `string`
`СписокАтрибутов`	`Строка`	`""`	`attributes_list`	Атрибуты строкой в формате `OTEL_RESOURCE_ATTRIBUTES`: `key1=value1,key2=value2`, значения в percent-encoding. При совпадении ключей важнее `Атрибуты`. Строка, которая не разбирается в этом формате, — исключение фабрики
`АдресСхемы`	`Строка`	`""`	`schema_url`	URL схемы ресурса; `""` — не задан

ОтелКонфигурацияЛимитовАтрибутов

Секции attribute_limits (поле ОтелКонфигурация.ЛимитыАтрибутов) и logger_provider.limits (поле Лимиты провайдера логирования).

Поле	Тип	По умолчанию	Ключ в файле	Описание
`МаксДлинаЗначенияАтрибута`	`Число`, `Неопределено`	`Неопределено`	`attribute_value_length_limit`	Максимальная длина значения атрибута; `Неопределено` — не задана
`МаксГлубинаЗначенияАтрибута`	`Число`, `Неопределено`	`Неопределено`	`attribute_value_depth_limit`	Максимальная глубина значения атрибута: глубина верхнего значения — 1, массивы и соответствия глубже лимита заменяются пустым значением. Не меньше 1; `Неопределено` — не задана
`МаксКоличествоАтрибутов`	`Число`, `Неопределено`	`Неопределено`	`attribute_count_limit`	Максимальное количество атрибутов; `Неопределено` — не задано

Лимит, заданный в limits провайдера (tracer_provider.limits, logger_provider.limits), перекрывает такой же лимит attribute_limits, как требует схема файла; лимит, не заданный в limits, фабрика берёт из attribute_limits (см. СоздатьПровайдерТрассировки и СоздатьПровайдерЛогирования на странице фабрики). Не заданное нигде количество атрибутов — 128, длина значения — без ограничения, глубина значения — 64.

ОтелКонфигурацияПропагатора

Секция propagator, поле ОтелКонфигурация.Пропагатор. Пропагаторы по ней создаёт ОтелКонфигурационнаяФабрика.СоздатьПропагаторы.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Составной`	`Массив` из `ОтелКонфигурацияКомпонента`	пустой массив	`composite`	Пропагаторы: элемент списка — объект с одним ключом, именем пропагатора (`- tracecontext:`); `Имя` — этот ключ, `Свойства` — значение под ним
`СписокСоставного`	`Строка`	`""`	`composite_list`	Имена пропагаторов через запятую, как в `OTEL_PROPAGATORS`; фабрика добавляет их после имён из `Составной`

ОтелКонфигурацияПровайдераТрассировки

Секция tracer_provider, поле ОтелКонфигурация.ПровайдерТрассировки. Провайдер по ней создаёт ОтелКонфигурационнаяФабрика.СоздатьПровайдерТрассировки.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Процессоры`	`Массив` из `ОтелКонфигурацияПакетногоПроцессора`, `ОтелКонфигурацияПростогоПроцессора`, `ОтелКонфигурацияКомпонента`	пустой массив	`processors`	Процессоры спанов по элементам списка в порядке файла: `- batch:`, `- simple:`; процессор, которого нет в SDK, — `ОтелКонфигурацияКомпонента`. Обязателен хотя бы один процессор: провайдер без процессоров фабрика не создаёт
`Лимиты`	`ОтелКонфигурацияЛимитовСпана`, `Неопределено`	`Неопределено`	`limits`	Лимиты спана; `Неопределено` — лимиты из `attribute_limits` и значения по умолчанию
`Сэмплер`	`ОтелКонфигурацияСэмплера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`sampler`	Сэмплер; `Неопределено` — `parent_based` с корневым `always_on`; сэмплер, которого нет в SDK, — `ОтелКонфигурацияКомпонента`
`ГенераторИд`	`ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`id_generator`	Генератор trace ID и span ID, в SDK есть `random`; `Неопределено` — `random`

ОтелКонфигурацияЛимитовСпана

Секция tracer_provider.limits, поле Лимитыпровайдера трассировки. Фабрика создаёт по ней ОтелЛимитыСпана. Как первые три поля сочетаются с attribute_limits, см. ОтелКонфигурацияЛимитовАтрибутов.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`МаксДлинаЗначенияАтрибута`	`Число`, `Неопределено`	`Неопределено`	`attribute_value_length_limit`	Максимальная длина значения атрибута спана; `Неопределено` — не задана
`МаксГлубинаЗначенияАтрибута`	`Число`, `Неопределено`	`Неопределено`	`attribute_value_depth_limit`	Максимальная глубина значения атрибута спана, не меньше 1; `Неопределено` — не задана
`МаксКоличествоАтрибутов`	`Число`, `Неопределено`	`Неопределено`	`attribute_count_limit`	Максимальное количество атрибутов спана; `Неопределено` — не задано
`МаксСобытий`	`Число`	`128`	`event_count_limit`	Максимальное количество событий спана
`МаксЛинков`	`Число`	`128`	`link_count_limit`	Максимальное количество линков спана
`МаксАтрибутовНаСобытие`	`Число`	`128`	`event_attribute_count_limit`	Максимальное количество атрибутов события
`МаксАтрибутовНаЛинк`	`Число`	`128`	`link_attribute_count_limit`	Максимальное количество атрибутов линка

ОтелКонфигурацияСэмплера

Секция tracer_provider.sampler (поле Сэмплерпровайдера трассировки) и вложенные сэмплеры parent_based и always_record. В секции сэмплера один ключ — тип сэмплера, под ключом — его параметры:

yaml

sampler:
  parent_based:
    root:
      trace_id_ratio_based:
        ratio: 0.1
    remote_parent_not_sampled:
      always_off:

yaml

# процессоры получают все спаны, экспортер - 10% трассировок
sampler:
  always_record:
    root:
      trace_id_ratio_based:
        ratio: 0.1

Вложенные сэмплеры разбор заполняет только у parent_based и always_record. Сэмплер, которого нет в SDK (например, composite/development или сэмплер пользователя), в том числе вложенный, разбор сохраняет как ОтелКонфигурацияКомпонента.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Тип`	`Строка`	`""`	имя ключа: `always_on`, `always_off`, `trace_id_ratio_based`, `parent_based`, `always_record`	Тип сэмплера — имя ключа схемы, регистр значим: `ALWAYS_ON` — сэмплер, которого нет в SDK. Что фабрика делает с пустым и нераспознанным типом, см. `СоздатьПровайдерТрассировки` на её странице
`Доля`	`Число`	`1.0`	`trace_id_ratio_based.ratio`	Доля сэмплируемых трассировок, от 0 до 1; разбор заполняет её только у `trace_id_ratio_based`. У каждого сэмплера `trace_id_ratio_based`, в том числе вложенного, своя доля, см. ОтелСэмплер
`Корневой`	`ОтелКонфигурацияСэмплера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`parent_based.root`, `always_record.root`	У `parent_based` — сэмплер спанов без родителя, `Неопределено` — `always_on`. У `always_record` — обёрнутый сэмплер, обязательный: без него фабрика выбрасывает исключение
`УдаленныйРодительСэмплирован`	`ОтелКонфигурацияСэмплера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`parent_based.remote_parent_sampled`	Сэмплер спанов, у которых удалённый родитель сэмплирован; `Неопределено` — `always_on`
`УдаленныйРодительНеСэмплирован`	`ОтелКонфигурацияСэмплера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`parent_based.remote_parent_not_sampled`	Сэмплер спанов, у которых удалённый родитель не сэмплирован; `Неопределено` — `always_off`
`ЛокальныйРодительСэмплирован`	`ОтелКонфигурацияСэмплера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`parent_based.local_parent_sampled`	Сэмплер спанов, у которых локальный родитель сэмплирован; `Неопределено` — `always_on`
`ЛокальныйРодительНеСэмплирован`	`ОтелКонфигурацияСэмплера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`parent_based.local_parent_not_sampled`	Сэмплер спанов, у которых локальный родитель не сэмплирован; `Неопределено` — `always_off`

ОтелКонфигурацияПровайдераМетрик

Секция meter_provider, поле ОтелКонфигурация.ПровайдерМетрик. Провайдер по ней создаёт ОтелКонфигурационнаяФабрика.СоздатьПровайдерМетрик.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Читатели`	`Массив` из `ОтелКонфигурацияПериодическогоЧитателя`, `ОтелКонфигурацияPullЧитателя`	пустой массив	`readers`	Читатели метрик по элементам списка в порядке файла: `- periodic:`, `- pull:`. Обязателен хотя бы один читатель: провайдер без читателей фабрика не создаёт
`ФильтрЭкземпляров`	`Строка`	`"trace_based"`	`exemplar_filter`	Фильтр exemplars: `trace_based`, `always_on` или `always_off`; другое значение, в том числе в другом регистре, не проходит проверку модели
`Представления`	`Массив` из `ОтелКонфигурацияПредставления`	пустой массив	`views`	Представления (View) по элементам списка в порядке файла; пустой массив — без представлений

ОтелКонфигурацияПредставления

Элемент списка views в секции meter_provider. Фабрика регистрирует по нему представление (ОтелСелекторИнструментов и ОтелПредставление) в провайдере метрик до выдачи метров, поэтому представление применяется ко всем инструментам провайдера. Правила применения представлений — в описании ОтелПредставление.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Селектор`	`ОтелКонфигурацияСелектораИнструментов`	новый объект	`selector`	Какие инструменты выбирает представление. Обязательное поле: `Неопределено` не проходит проверку модели
`Поток`	`ОтелКонфигурацияПотокаМетрики`	новый объект	`stream`	Настройки потока метрики выбранных инструментов. Обязательное поле: `Неопределено` не проходит проверку модели

ОтелКонфигурацияСелектораИнструментов

Секция selector представления. Инструмент выбирается, если соответствует всем заданным критериям; критерий Неопределено не задан — ему соответствует любой инструмент. Пустая строка — значение критерия: Единица = "" выбирает инструменты без единицы измерения.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`ИмяИнструмента`	`Строка`, `Неопределено`	`Неопределено`	`instrument_name`	Имя инструмента без учёта регистра; `*` — все инструменты
`ТипИнструмента`	`Строка`, `Неопределено`	`Неопределено`	`instrument_type`	Вид инструмента: `counter`, `up_down_counter`, `histogram`, `gauge`, `observable_counter`, `observable_up_down_counter` или `observable_gauge`; другое значение не проходит проверку модели
`Единица`	`Строка`, `Неопределено`	`Неопределено`	`unit`	Единица измерения инструмента
`ИмяМетра`	`Строка`, `Неопределено`	`Неопределено`	`meter_name`	Имя метра, создавшего инструмент
`ВерсияМетра`	`Строка`, `Неопределено`	`Неопределено`	`meter_version`	Версия метра. Версию в файле пишите в кавычках, если YAML может прочитать её как число (`"1.0"`)
`АдресСхемыМетра`	`Строка`, `Неопределено`	`Неопределено`	`meter_schema_url`	Адрес схемы метра

ОтелКонфигурацияПотокаМетрики

Секция stream представления. Настройка Неопределено не задана: поток берёт её у инструмента или читателя.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Имя`	`Строка`, `Неопределено`	`Неопределено`	`name`	Имя потока метрики; `Неопределено` — имя инструмента
`Описание`	`Строка`, `Неопределено`	`Неопределено`	`description`	Описание потока; `Неопределено` — описание инструмента
`Агрегация`	`ОтелКонфигурацияАгрегации`, `Неопределено`	`Неопределено`	`aggregation`	Агрегация потока; `Неопределено` — агрегация по умолчанию (`default`)
`ЛимитМощностиАгрегации`	`Число`, `Неопределено`	`Неопределено`	`aggregation_cardinality_limit`	Лимит мощности потока — целое число больше 0; `Неопределено` — лимит читателя (см. `ОтелКонфигурацияЛимитовМощности`)
`КлючиАтрибутов`	`ОтелКонфигурацияКлючейАтрибутов`, `Неопределено`	`Неопределено`	`attribute_keys`	Какие атрибуты измерений сохраняет поток; `Неопределено` — все

ОтелКонфигурацияАгрегации

Секция aggregation потока: объект с одним ключом — типом агрегации. Фабрика создаёт по ней агрегацию ОтелАгрегация. Параметры есть только у гистограмм, у других типов их нет.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Тип`	`Строка`	`"default"`	ключ секции	Тип агрегации: `default` (по виду инструмента), `drop`, `sum`, `last_value`, `explicit_bucket_histogram` или `base2_exponential_bucket_histogram`; другое значение не проходит проверку модели
`Границы`	`Массив` из `Число`, `Неопределено`	`Неопределено`	`boundaries`	Границы бакетов `explicit_bucket_histogram`; `Неопределено` — границы по умолчанию (0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000), advisory-границы инструмента не используются
`ЗаписыватьМинМакс`	`Булево`	`Истина`	`record_min_max`	Записывать min и max гистограмм обоих типов
`МаксШкала`	`Число`	`20`	`max_scale`	Максимальная шкала `base2_exponential_bucket_histogram` — целое от -10 до 20
`МаксРазмер`	`Число`	`160`	`max_size`	Максимальное число бакетов `base2_exponential_bucket_histogram` положительных и отдельно отрицательных значений — не меньше 2

Агрегация, несовместимая с видом инструмента (гистограмма для асинхронного инструмента), — семантическая ошибка представления: представление не применяется, в лог пишется предупреждение (см. ОтелПредставление).

ОтелКонфигурацияКлючейАтрибутов

Секция attribute_keys потока. Ключ списка — точное значение или шаблон: ? — любой один символ, * — любое число любых символов; ключи сравниваются с учётом регистра. Ключ, совпавший с обоими списками, отбрасывается.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Включенные`	`Массив` из `Строка`, `Неопределено`	`Неопределено`	`included`	Ключи атрибутов, которые сохраняет поток, остальные отбрасываются; `Неопределено` — все ключи. Пустой массив не проходит проверку модели
`Исключенные`	`Массив` из `Строка`, `Неопределено`	`Неопределено`	`excluded`	Ключи атрибутов, которые поток отбрасывает; `Неопределено` — ни одного. Пустой массив не проходит проверку модели

ОтелКонфигурацияПровайдераЛогирования

Секция logger_provider, поле ОтелКонфигурация.ПровайдерЛогирования. Провайдер по ней создаёт ОтелКонфигурационнаяФабрика.СоздатьПровайдерЛогирования.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Процессоры`	`Массив` из `ОтелКонфигурацияПакетногоПроцессора`, `ОтелКонфигурацияПростогоПроцессора`, `ОтелКонфигурацияКомпонента`	пустой массив	`processors`	Процессоры записей логов по элементам списка в порядке файла: `- batch:`, `- simple:`; `- event_to_span_event_bridge/development:` и процессор, которого нет в SDK, — `ОтелКонфигурацияКомпонента`. Обязателен хотя бы один процессор: провайдер без процессоров фабрика не создаёт
`Лимиты`	`ОтелКонфигурацияЛимитовАтрибутов`, `Неопределено`	`Неопределено`	`limits`	Лимиты записей лога; `Неопределено` — лимиты из `attribute_limits` и значения по умолчанию

ОтелКонфигурацияПакетногоПроцессора

Элемент - batch: списка processors в секциях tracer_provider и logger_provider. Фабрика создаёт по нему ОтелПакетныйПроцессорСпанов или ОтелПакетныйПроцессорЛогов.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`ЗадержкаОтправки`	`Число`, `Неопределено`	`Неопределено`; при разборе — `5000` в `tracer_provider` и `1000` в `logger_provider`	`schedule_delay`	Интервал фонового экспорта, мс; `Неопределено` — 5000 у спанов, 1000 у записей лога
`ТаймаутЭкспорта`	`Число`	`30000`	`export_timeout`	Таймаут экспорта, мс
`МаксРазмерОчереди`	`Число`	`2048`	`max_queue_size`	Максимальный размер очереди
`МаксРазмерПакета`	`Число`	`512`	`max_export_batch_size`	Максимальный размер пакета экспорта
`Экспортер`	`ОтелКонфигурацияЭкспортераOtlpHttp`, `ОтелКонфигурацияЭкспортераOtlpGrpc`, `ОтелКонфигурацияКонсольногоЭкспортера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`exporter`	Обязательный экспортер: процессор без экспортера фабрика не создаёт — выбрасывает исключение. Экспортер, которого нет в SDK, — `ОтелКонфигурацияКомпонента`

ОтелКонфигурацияПростогоПроцессора

Элемент - simple: списка processors в секциях tracer_provider и logger_provider. Фабрика создаёт по нему ОтелПростойПроцессорСпанов или ОтелПростойПроцессорЛогов: спан или запись лога экспортируется сразу, без очереди.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Экспортер`	`ОтелКонфигурацияЭкспортераOtlpHttp`, `ОтелКонфигурацияЭкспортераOtlpGrpc`, `ОтелКонфигурацияКонсольногоЭкспортера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`exporter`	Обязательный экспортер: процессор без экспортера фабрика не создаёт — выбрасывает исключение. Экспортер, которого нет в SDK, — `ОтелКонфигурацияКомпонента`

ОтелКонфигурацияПериодическогоЧитателя

Элемент - periodic: списка readers в секции meter_provider. Фабрика создаёт по нему ОтелПериодическийЧитательМетрик.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Интервал`	`Число`	`60000`	`interval`	Интервал периодического экспорта, мс
`Таймаут`	`Число`	`30000`	`timeout`	Таймаут экспорта, мс
`Экспортер`	`ОтелКонфигурацияЭкспортераOtlpHttp`, `ОтелКонфигурацияЭкспортераOtlpGrpc`, `ОтелКонфигурацияКонсольногоЭкспортера`, `ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`exporter`	Обязательный экспортер: читатель без экспортера фабрика не создаёт — выбрасывает исключение. Экспортер, которого нет в SDK, — `ОтелКонфигурацияКомпонента`
`Продюсеры`	`Массив` из `ОтелКонфигурацияКомпонента`	пустой массив	`producers`	Продюсеры метрик по элементам списка в порядке файла. Встроенных продюсеров в SDK нет: продюсер создаёт провайдер компонента, без провайдера фабрика выбрасывает исключение
`ЛимитыМощности`	`ОтелКонфигурацияЛимитовМощности`, `Неопределено`	`Неопределено`	`cardinality_limits`	Лимиты мощности читателя по видам инструментов; `Неопределено` — 2000 для всех видов

ОтелКонфигурацияPullЧитателя

Элемент - pull: списка readers в секции meter_provider. Встроенного pull-экспортера в SDK нет: фабрика создаёт читатель провайдером компонента, зарегистрированным с типом ОтелТипКомпонентаКонфигурации.ЧитательМетрикPull() и именем pull-экспортера, затем добавляет ему продюсеры и лимиты мощности (см. ОтелКонфигурационнаяФабрика, «Компоненты, которых нет в SDK»). Без провайдера фабрика выбрасывает исключение.

yaml

readers:
  - pull:
      exporter:
        my_pull_exporter:   # Экспортер.Имя
          port: 9464        # Экспортер.Свойства

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Экспортер`	`ОтелКонфигурацияКомпонента`, `Неопределено`	`Неопределено`	`exporter`	Обязательный pull-экспортер: имя и свойства из файла
`Продюсеры`	`Массив` из `ОтелКонфигурацияКомпонента`	пустой массив	`producers`	Продюсеры метрик, как у периодического читателя
`ЛимитыМощности`	`ОтелКонфигурацияЛимитовМощности`, `Неопределено`	`Неопределено`	`cardinality_limits`	Лимиты мощности по видам инструментов: вид без своего лимита получает `default`; `Неопределено` — лимиты читателя, созданного провайдером

ОтелКонфигурацияЛимитовМощности

Секция cardinality_limits периодического читателя, поле ЛимитыМощности. Лимит мощности (cardinality limit) — сколько разных наборов атрибутов поток метрики одного инструмента хранит за цикл сбора, см. ОтелПериодическийЧитательМетрик. Лимит — целое число больше 0. Лимит вида инструмента со значением Неопределено не задан: вид берёт ПоУмолчанию. Лимит, заданный View, важнее лимита читателя.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`ПоУмолчанию`	`Число`	`2000`	`default`	Лимит для видов инструментов без своего лимита; `Неопределено` — 2000
`Счетчик`	`Число`, `Неопределено`	`Неопределено`	`counter`	Лимит счётчиков (`СоздатьСчетчик`)
`РеверсивныйСчетчик`	`Число`, `Неопределено`	`Неопределено`	`up_down_counter`	Лимит реверсивных счётчиков (`СоздатьРеверсивныйСчетчик`)
`Гистограмма`	`Число`, `Неопределено`	`Неопределено`	`histogram`	Лимит гистограмм (`СоздатьГистограмму`)
`Датчик`	`Число`, `Неопределено`	`Неопределено`	`gauge`	Лимит датчиков (`СоздатьДатчик`)
`НаблюдаемыйСчетчик`	`Число`, `Неопределено`	`Неопределено`	`observable_counter`	Лимит наблюдаемых счётчиков (`СоздатьНаблюдаемыйСчетчик`)
`НаблюдаемыйРеверсивныйСчетчик`	`Число`, `Неопределено`	`Неопределено`	`observable_up_down_counter`	Лимит наблюдаемых реверсивных счётчиков (`СоздатьНаблюдаемыйРеверсивныйСчетчик`)
`НаблюдаемыйДатчик`	`Число`, `Неопределено`	`Неопределено`	`observable_gauge`	Лимит наблюдаемых датчиков (`СоздатьНаблюдаемыйДатчик`)

ОтелКонфигурацияЭкспортераOtlpHttp

Ключ exporter.otlp_http процессора и периодического читателя. Фабрика создаёт по нему ОтелHttpТранспорт с протоколом http/protobuf и экспортер сигнала. Ключ без значения (otlp_http:) задаёт экспортер с настройками по умолчанию.

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Адрес`	`Строка`	`""`	`endpoint`	Полный адрес вместе с путём сигнала, например `http://localhost:4318/v1/traces`: URL со схемой `http` или `https`, другой адрес — исключение фабрики; `""` — `http://localhost:4318/v1/<сигнал>`
`Сжатие`	`Строка`	`""`	`compression`	`gzip` — сжатие gzip; `none` и `""` — без сжатия. Другое значение, в том числе в другом регистре, — исключение фабрики
`Таймаут`	`Число`	`10000`	`timeout`	Срок каждого экспорта вместе с повторами и таймаут HTTP-запроса, мс; `0` — без ограничения
`Заголовки`	`Массив` из `Структура`	пустой массив	`headers`	HTTP-заголовки — структуры с полями `Имя` (из `name`) и `Значение` (строка из `value`). Заголовок `value: null` разбор пропускает, как требует схема; заголовок со значением `Неопределено` в модели из кода пропускает фабрика
`СписокЗаголовков`	`Строка`	`""`	`headers_list`	Заголовки строкой в формате `OTEL_EXPORTER_OTLP_HEADERS`: `key1=value1,key2=value2`, значения в percent-encoding. При совпадении имён действует значение из `Заголовки`. Строка, которая не разбирается в этом формате, — исключение фабрики
`ПредпочтениеВременнойАгрегации`	`Строка`	`""`	`temporality_preference`	Временная агрегация метрик: `cumulative`, `delta` или `low_memory`; `""` — `cumulative`. Другое значение, в том числе в другом регистре, не проходит проверку модели
`АгрегацияГистограммПоУмолчанию`	`Строка`	`""`	`default_histogram_aggregation`	Агрегация гистограмм по умолчанию: `explicit_bucket_histogram` или `base2_exponential_bucket_histogram`; `""` — `explicit_bucket_histogram`. Другое значение не проходит проверку модели
`МаксРазмерЗапроса`	`Число`	`67108864`	`max_request_size`	Наибольший размер тела запроса до сжатия, байт: запрос больше лимита не отправляется, экспорт неуспешен; `0` — без ограничения
`МаксРазмерОтвета`	`Число`	`4194304`	`max_response_size`	Наибольший размер ответа, байт, не меньше 1: экспорт с ответом больше лимита неуспешен
`Кодирование`	`Строка`	`""`	`encoding`	Кодирование сообщений: `protobuf` — протокол `http/protobuf`, `json` — `http/json`; `""` — `protobuf`. Другое значение, в том числе в другом регистре, не проходит проверку модели
`НастройкиTls`	`ОтелНастройкиTls`, `Неопределено`	`Неопределено`	`tls`	Файлы TLS: `ФайлСертификата` (`ca_file`), `ФайлКлиентскогоКлюча` (`key_file`), `ФайлКлиентскогоСертификата` (`cert_file`) — абсолютные пути к существующим файлам, ключ и сертификат клиента задаются вместе, иначе исключение фабрики. HTTP-клиент OneScript файлы не применяет — транспорт предупреждает в логе. `Insecure` у `otlp_http` не задаётся: в схеме его нет. `Неопределено` — настройки TLS по умолчанию

Поля ПредпочтениеВременнойАгрегации и АгрегацияГистограммПоУмолчанию — настройки экспортера метрик: по схеме ключи temporality_preference и default_histogram_aggregation есть только у экспортера периодического читателя, у экспортера процессора они — ошибка разбора, а заполненные в модели — ошибка проверки модели.

ОтелКонфигурацияЭкспортераOtlpGrpc

Ключ exporter.otlp_grpc процессора и периодического читателя. Фабрика создаёт по нему ОтелGrpcТранспорт и экспортер сигнала. Ключ без значения (otlp_grpc:) задаёт экспортер с настройками по умолчанию. Поля те же, что у ОтелКонфигурацияЭкспортераOtlpHttp, кроме адреса, сжатия и размера ответа; кодирования у otlp_grpc нет — сообщения gRPC всегда protobuf:

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Адрес`	`Строка`	`""`	`endpoint`	Адрес коллектора без пути сигнала: URL со схемой `http` или `https`, например `http://collector:4317`, или адрес без схемы (`collector:4317`) — соединение с TLS, при `tls.insecure: true` — без TLS. Сервис сигнала gRPC-транспорт выбирает сам. Адрес с другой схемой — исключение фабрики; `""` — `http://localhost:4317`
`Сжатие`	`Строка`	`""`	`compression`	Сжатие клиент OPI_GRPC не поддерживает (OpenIntegrations#112): при `gzip` фабрика пишет предупреждение в лог, данные отправляются без сжатия. `none` и `""` — без сжатия, другое значение — исключение фабрики
`Таймаут`	`Число`	`10000`	`timeout`	Срок каждого экспорта вместе с повторами и таймаут вызова gRPC, мс; `0` — без ограничения
`Заголовки`	`Массив` из `Структура`	пустой массив	`headers`	Метаданные вызова gRPC — структуры с полями `Имя` и `Значение`, как у `otlp_http`
`СписокЗаголовков`	`Строка`	`""`	`headers_list`	Метаданные строкой в формате `OTEL_EXPORTER_OTLP_HEADERS`. При совпадении имён действует значение из `Заголовки`
`ПредпочтениеВременнойАгрегации`	`Строка`	`""`	`temporality_preference`	Временная агрегация метрик, как у `otlp_http`
`АгрегацияГистограммПоУмолчанию`	`Строка`	`""`	`default_histogram_aggregation`	Агрегация гистограмм по умолчанию, как у `otlp_http`
`МаксРазмерЗапроса`	`Число`	`67108864`	`max_request_size`	Наибольший размер сообщения запроса до сжатия, байт, как у `otlp_http`; `0` — без ограничения
`МаксРазмерОтвета`	`Число`	`4194304`	`max_response_size`	Клиент OPI_GRPC принимает ответ не больше 4 MiB, другой лимит задать нельзя (OpenIntegrations#113): при другом значении фабрика пишет предупреждение в лог, действует лимит 4 MiB
`НастройкиTls`	`ОтелНастройкиTls`, `Неопределено`	`Неопределено`	`tls`	Файлы TLS, как у `otlp_http`, и `Insecure` (`insecure`): `Истина` — соединение без TLS с адресом без схемы. Сертификат сервера транспорт проверяет по `ФайлСертификата`; клиентский ключ и сертификат (mTLS) клиент OPI_GRPC не поддерживает (OpenIntegrations#102) — транспорт предупреждает в логе

ОтелКонфигурацияКонсольногоЭкспортера

Ключ exporter.console процессора и периодического читателя. Фабрика создаёт по нему ОтелКонсольныйТранспорт и экспортер сигнала: каждый экспорт выводится в стандартный вывод одной строкой OTLP JSON. Срок экспорта — 10000 мс. Ключ без значения (console:) задаёт экспортер с настройками по умолчанию. Свойства есть только у экспортера метрик; у экспортера спанов и записей логов любое свойство — ошибка схемы:

Поле	Тип	По умолчанию	Ключ в файле	Описание
`ПредпочтениеВременнойАгрегации`	`Строка`	`""`	`temporality_preference`	Временная агрегация метрик, как у `otlp_http`
`АгрегацияГистограммПоУмолчанию`	`Строка`	`""`	`default_histogram_aggregation`	Агрегация гистограмм по умолчанию, как у `otlp_http`

ОтелКонфигурацияКомпонента

Компонент, заданный в файле ключом-именем со свойствами под ним:

пропагатор — элемент списка propagator.composite (- tracecontext:);
генератор ID — секция tracer_provider.id_generator (random:);
компонент, которого нет в SDK, на месте экспортера, процессора, pull-экспортера, продюсера метрик, сэмплера, пропагатора или генератора ID, например экспортер пользователя:

yaml

exporter:
  my_exporter:            # Имя
    url: http://example   # Свойства

Спецификация Configuration SDK (Parse) требует сохранять конфигурацию компонента, которого нет в SDK, в общем виде. Фабрика создаёт такой компонент провайдером компонента, который получает Свойства как ОтелСвойстваКонфигурации; без провайдера — исключение (см. ОтелКонфигурационнаяФабрика, «Компоненты, которых нет в SDK»).

Поле	Тип	По умолчанию	Ключ в файле	Описание
`Имя`	`Строка`	`""`	ключ компонента	Имя компонента, например `tracecontext`, `random`, `my_exporter`
`Свойства`	`Соответствие`, `Неопределено`	`Неопределено`	значение под ключом	Свойства компонента как в файле — `Соответствие`, значения которого прочитаны из YAML без преобразования; `Неопределено` — ключ без значения (`my_exporter:`)

Пример

bsl

#Использовать opentelemetry

Модель = ОтелФайловаяКонфигурация.Разобрать("/etc/otel/config.yaml");

// Секции tracer_provider может не быть в файле: тогда SDK получает no-op провайдер трассировки
Провайдер = Модель.ПровайдерТрассировки;
Если Провайдер <> Неопределено Тогда

    // Другой адрес у экспортеров otlp_http всех процессоров спанов
    Для Каждого Процессор Из Провайдер.Процессоры Цикл
        Если ТипЗнч(Процессор) <> Тип("ОтелКонфигурацияКомпонента")
            И ТипЗнч(Процессор.Экспортер) = Тип("ОтелКонфигурацияЭкспортераOtlpHttp") Тогда
            Процессор.Экспортер.Адрес = "http://collector:4318/v1/traces";
        КонецЕсли;
    КонецЦикла;

    // Сэмплер parent_based: 10% новых трассировок
    Корневой = Новый ОтелКонфигурацияСэмплера();
    Корневой.Тип = "trace_id_ratio_based";
    Корневой.Доля = 0.1;
    Сэмплер = Новый ОтелКонфигурацияСэмплера();
    Сэмплер.Тип = "parent_based";
    Сэмплер.Корневой = Корневой;
    Провайдер.Сэмплер = Сэмплер;

КонецЕсли;

// Фабрика читает поля модели в момент вызова и проверяет измененную модель по схеме
Сдк = ОтелКонфигурационнаяФабрика.Создать(Модель);
ОтелГлобальный.Установить(Сдк);
// ...
Сдк.Закрыть();

bsl

// Модель без файла: спаны отправляются по OTLP/HTTP, пропагаторы W3C
Экспортер = Новый ОтелКонфигурацияЭкспортераOtlpHttp();
Экспортер.Адрес = "http://collector:4318/v1/traces";

Процессор = Новый ОтелКонфигурацияПакетногоПроцессора();
Процессор.Экспортер = Экспортер;

Модель = Новый ОтелКонфигурация();
Модель.ФорматФайла = "1.0";
Модель.Ресурс = Новый ОтелКонфигурацияРесурса();
Модель.Ресурс.Атрибуты.Добавить(Новый Структура("Имя, Значение", "service.name", "мой-сервис"));
Модель.ПровайдерТрассировки = Новый ОтелКонфигурацияПровайдераТрассировки();
Модель.ПровайдерТрассировки.Процессоры.Добавить(Процессор);
Модель.Пропагатор = Новый ОтелКонфигурацияПропагатора();
Модель.Пропагатор.СписокСоставного = "tracecontext,baggage";

// Секций meter_provider и logger_provider нет: у SDK только провайдер трассировки
Сдк = ОтелКонфигурационнаяФабрика.Создать(Модель);

См. также

ОтелСвойстваКонфигурации

Свойства компонента из файла конфигурации (ConfigProperties).

Описание

Узел-соответствие YAML, который фабрика передаёт провайдеру компонента в СоздатьКомпонент(Свойства) (см. ОтелКонфигурационнаяФабрика.ЗарегистрироватьПровайдерКомпонента). Соответствует ConfigProperties спецификации Configuration API: даёт доступ ко всем свойствам узла — скалярам, вложенным соответствиям, последовательностям скаляров и соответствий, а также к списку ключей.

Каждое значение читается типизированным геттером:

свойства нет — геттер возвращает значение по умолчанию (параметр ПоУмолчанию, если не задан — Неопределено);
свойство задано со значением null (timeout: без значения) — геттер возвращает Null: null и отсутствие свойства — разные случаи (nullBehavior и defaultBehavior схемы компонента);
значение не того типа — исключение Свойство "<имя>": ожидается <тип>. Спецификация Configuration SDK требует, чтобы Create Component при несовпадении типа возвращал ошибку, и геттер даёт её сразу: фабрика передаёт исключение из Создать.

Содержит и ЭтоNull проверяют, задано ли свойство и равно ли оно null. Вложенное соответствие читается как ОтелСвойстваКонфигурации.

Узел хранится в неизменяемых коллекциях collectionos: соответствия — ФиксированнаяКарта, последовательности — ФиксированныйСписок, null — Null. Узел копируется при создании, поэтому изменения исходного соответствия свойства не меняют. Массивы, которые возвращают методы, — новые массивы.

Конструктор

bsl

Новый ОтелСвойстваКонфигурации(ДанныеУзла)

Параметр	Тип	По умолчанию	Описание
`ДанныеУзла`	`Соответствие`, `ФиксированноеСоответствие`, `Неопределено`	—	Свойства компонента из файла; `Неопределено` в значении свойства — null; `Неопределено` вместо узла — компонент без свойств (`my_exporter:`)

Фабрика создаёт объект сама; создавать его нужно, например, в тестах провайдера компонента.

Методы

Метод	Значение свойства	Возвращает
`ПолучитьСтроку(Имя, ПоУмолчанию = Неопределено)`	строка	`Строка`
`ПолучитьБулево(Имя, ПоУмолчанию = Неопределено)`	`true` или `false`	`Булево`
`ПолучитьЦелое(Имя, ПоУмолчанию = Неопределено)`	целое число	`Число`
`ПолучитьЧисло(Имя, ПоУмолчанию = Неопределено)`	число, целое или дробное	`Число`
`ПолучитьСвойства(Имя, ПоУмолчанию = Неопределено)`	соответствие	`ОтелСвойстваКонфигурации`
`ПолучитьМассивСтрок(Имя, ПоУмолчанию = Неопределено)`	последовательность строк	`Массив` из `Строка`
`ПолучитьМассивБулево(Имя, ПоУмолчанию = Неопределено)`	последовательность булевых значений	`Массив` из `Булево`
`ПолучитьМассивЦелых(Имя, ПоУмолчанию = Неопределено)`	последовательность целых чисел	`Массив` из `Число`
`ПолучитьМассивЧисел(Имя, ПоУмолчанию = Неопределено)`	последовательность чисел	`Массив` из `Число`
`ПолучитьМассивСвойств(Имя, ПоУмолчанию = Неопределено)`	последовательность соответствий	`Массив` из `ОтелСвойстваКонфигурации`
`Ключи()`	—	`Массив` из `Строка` — имена всех заданных свойств, в том числе со значением null
`Содержит(Имя)`	—	`Булево` — свойство задано, в том числе со значением null
`ЭтоNull(Имя)`	—	`Булево` — свойство задано со значением null

Каждый геттер возвращает значение свойства, Null для свойства со значением null или ПоУмолчанию, если свойства нет. Значение не того типа и последовательность с элементом другого типа дают исключение с именем свойства и ожидаемым типом.

Пример

yaml

exporter:
  my_exporter:
    endpoint: http://collector:9000
    timeout: 5000
    tags: [a, b]
    tls:
      insecure: true

bsl

Функция СоздатьКомпонент(Свойства) Экспорт
    Адрес = Свойства.ПолучитьСтроку("endpoint");                 // "http://collector:9000"
    Таймаут = Свойства.ПолучитьЦелое("timeout", 10000);           // 5000
    Метки = Свойства.ПолучитьМассивСтрок("tags", Новый Массив);   // ["a", "b"]
    // tls нет - без TLS; tls: (null) - TLS с настройками по умолчанию; tls со свойствами - по ним
    Tls = Свойства.ПолучитьСвойства("tls");
    Если Tls = Null Тогда
        Tls = Новый ОтелСвойстваКонфигурации(Неопределено);
    КонецЕсли;
    БезTls = Tls = Неопределено Или Tls.ПолучитьБулево("insecure", Ложь);
    // Свойства.ПолучитьЦелое("endpoint") - исключение: Свойство "endpoint": ожидается целое число
    // ...
КонецФункции

См. также

ОтелТипКомпонентаКонфигурации

Модуль — перечисление типов компонентов, которые файл конфигурации создаёт через провайдеры компонентов.

Описание

Тип компонента передаётся в ОтелКонфигурационнаяФабрика.ЗарегистрироватьПровайдерКомпонента вместе с именем компонента. Значение — имя типа схемы конфигурации (спецификация Configuration SDK, Supported SDK plugin components). Провайдер возвращает компонент указанного типа.

Функции-константы

Функция	Значение	Где в файле конфигурации	Что возвращает провайдер
`Пропагатор()`	`"TextMapPropagator"`	элемент `propagator.composite`, имя в `propagator.composite_list`	пропагатор с методами `Внедрить`, `Извлечь`, `Поля`
`ЭкспортерСпанов()`	`"SpanExporter"`	`exporter` процессора `tracer_provider.processors`	экспортер спанов
`ПроцессорСпанов()`	`"SpanProcessor"`	элемент `tracer_provider.processors`	процессор спанов
`Сэмплер()`	`"Sampler"`	`tracer_provider.sampler`, сэмплеры в `parent_based` и `always_record`	сэмплер (ИнтерфейсСэмплер)
`ГенераторИд()`	`"IdGenerator"`	`tracer_provider.id_generator`	генератор с методами `СгенерироватьИдТрассировки`, `СгенерироватьИдСпана`
`ЧитательМетрикPull()`	`"PullMetricExporter"`	`exporter` читателя `pull`	читатель метрик, например ОтелПрометеусЧитательМетрик
`ЭкспортерМетрик()`	`"PushMetricExporter"`	`exporter` читателя `periodic`	экспортер метрик
`ПродюсерМетрик()`	`"MetricProducer"`	элемент `producers` читателя	продюсер метрик с методом `Произвести(Ресурс, ТаймаутМс)`
`ЭкспортерЗаписейЛога()`	`"LogRecordExporter"`	`exporter` процессора `logger_provider.processors`	экспортер записей лога
`ПроцессорЗаписейЛога()`	`"LogRecordProcessor"`	элемент `logger_provider.processors`	процессор записей лога

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

Пример

bsl

ОтелКонфигурационнаяФабрика.ЗарегистрироватьПровайдерКомпонента(
    Новый МойПровайдерСэмплера(), ОтелТипКомпонентаКонфигурации.Сэмплер(), "my_sampler");

См. также

ОтелФайловаяКонфигурация

Модуль файловой конфигурации OpenTelemetry SDK.

Описание

Читает YAML-файл конфигурации, выполняет подстановку переменных окружения и возвращает типизированную дата-модель (ОтелКонфигурация).

Реализует спецификацию:

Формат файла: YAML, обязательное поле file_format (поддерживается версия 1.x).

Проверка по схеме. Разобрать проверяет файл по схеме opentelemetry-configuration 1.2 (Configuration SDK / Parse): типы значений, обязательные свойства, допустимые значения перечислений, границы чисел и свойства, которых нет в схеме. Несоответствие — исключение, в тексте которого перечислены все нарушения с путём до свойства, например /tracer_provider/processors/0/batch/schedule_delay: Значение -1 меньше минимума 0. Проверку выполняет библиотека jsonschema, схема лежит в пакете (src/Конфигурация/Схема).

Версия file_format проверяется по правилам версионирования схемы: основная версия, кроме 1, — ошибка; более новая младшая версия (например, 1.3) — предупреждение в лог, а свойства, которых нет в схеме 1.2, разбор пропускает с предупреждением о каждом.

Подстановка переменных окружения выполняется при разборе по спецификации Environment variable substitution:

${ИМЯ} и ${env:ИМЯ} — значение переменной окружения; ${ИМЯ:-значение} — значение по умолчанию, если переменная не задана или пустая. Незаданная переменная без значения по умолчанию дает пустое значение. Имя переменной — латинские буквы, цифры и _, первый символ не цифра;
$$ — экранирование: $${ИМЯ} дает текст ${ИМЯ}, a $$ b — a $ b;
подстановка выполняется только в значениях: ключи и комментарии не меняются, ссылки в значении переменной повторно не подставляются;
тип значения определяется после подстановки: значение без кавычек получает тип, как если бы оно было записано в файле (schedule_delay: ${DELAY} при DELAY=5000 — число 5000, пустое значение — null), значение в кавычках остается строкой ("${DELAY}" — строка "5000");
значение переменной не добавляет в файл конструкций YAML: значение с переводом строки, коллекция [...] или {...}, якорь, алиас или комментарий остаются строкой;
ссылка другого вида (например, ${ИМЯ:?ошибка}, ${1ИМЯ} или ${sys:свойство}) в значении — ошибка разбора.

Значение блочного скаляра (| или >), целиком состоящее из подстановки, получает тип так же, как значение без кавычек: парсер YAML не различает эти стили.

Тип значения важен для атрибутов ресурса: значение атрибута должно соответствовать его type, а без type — быть строкой, иначе ОтелКонфигурационнаяФабрика.Создать выбрасывает исключение. Значение из переменной, которое может оказаться числом или булевым (value: ${SERVICE_VERSION} при SERVICE_VERSION=1.0 — число), пишите в кавычках: value: "${SERVICE_VERSION}".

Значение в кавычках в самом файле всегда строка (core schema YAML 1.2): value: "true", "123" и "null" — строки true, 123 и null.

Ограничение парсера YAML. Тип значения без кавычек (в самом файле и после подстановки переменной) определяет библиотека oscript-yaml 0.3.1, и она отступает от core schema: tRuE, fAlSe и nUlL читает как булево и null (по core schema это строки), 0o17 и 1e-3 — как строки (по core schema числа 15 и 0.001), а 1e3 (по core schema число 1000) в самом файле приводит к ошибке разбора, а из переменной остаётся строкой.

Методы модуля

Разобрать

Разбирает файл конфигурации и возвращает типизированную модель ОтелКонфигурация.

Параметр	Тип	По умолчанию	Описание
`ПутьКФайлу`	Строка	—	Путь к YAML-файлу конфигурации

Возвращает: ОтелКонфигурация — разобранная конфигурация

Исключения:

Файл не найден по указанному пути
Некорректная ссылка на переменную окружения в значении (см. «Подстановка переменных окружения»)
YAML не является маппингом верхнего уровня
Поле file_format не указано
Поле file_format не строка: по схеме это строка в кавычках, file_format: 1.0 без кавычек YAML читает как число
Версия формата не поддерживается (не 1.x)
Файл не соответствует схеме (см. «Проверка по схеме»)

ПроверитьВерсиюФормата

Проверяет версию формата file_format по правилам версионирования схемы: версия — MAJOR.MINOR с необязательной меткой (1.0, 1.0-rc.2), основная версия — 1. По ней проверяют версию Разобрать и ОтелКонфигурационнаяФабрика.Создать (модель, собранная в коде).

Параметр	Тип	По умолчанию	Описание
`ФорматФайла`	Строка	—	Значение `file_format`

Возвращает: Число — младшая версия формата

Исключения: версия не 1.x или записана не в формате MAJOR.MINOR

ПроверитьМодель

Проверяет модель ОтелКонфигурация по схеме файла конфигурации по тем же правилам, по которым Разобрать проверяет файл: типы значений, обязательные свойства, допустимые значения перечислений и границы чисел. Модель переводится обратно в данные с ключами схемы: незаданные значения модели (Неопределено, пустая строка, пустой список необязательного свойства) в данные не попадают, значение не того класса, что ожидает поле модели, проверка сообщает как значение не того типа. Так модель, собранная в коде, проходит ту же проверку, что и файл: спецификация Configuration SDK (Create) требует ошибку на значении, недопустимом по схеме. Модель проверяет ОтелКонфигурационнаяФабрика перед созданием SDK; вызывать функцию отдельно не нужно.

Параметр	Тип	По умолчанию	Описание
`Модель`	`ОтелКонфигурация`	—	Модель конфигурации

Исключения: модель не соответствует схеме. Текст перечисляет все нарушения с путём свойства схемы, например /tracer_provider/processors/0/batch/schedule_delay: Значение -1 меньше минимума 0

Пример

bsl

#Использовать opentelemetry

// Разобрать файл конфигурации
Конфигурация = ОтелФайловаяКонфигурация.Разобрать("/etc/otel/config.yaml");

// Создать SDK по конфигурации. При disabled: true фабрика возвращает SDK,
// который не собирает телеметрию
Сдк = ОтелКонфигурационнаяФабрика.Создать(Конфигурация);

Трассировщик = Сдк.ПолучитьТрассировщик("мой-сервис");

ОтелАвтоконфигурация.Инициализировать() делает то же самое, если путь к файлу задан в переменной окружения OTEL_CONFIG_FILE, и дополнительно регистрирует SDK в ОтелГлобальный.

Пример YAML-файла конфигурации:

yaml

file_format: "1.0"
disabled: false

resource:
  attributes:
    - name: service.name
      value: "${SERVICE_NAME}"
    - name: service.version
      value: "1.0.0"

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: "${OTLP_ENDPOINT}"

Пропагаторы задаются в секции propagator списком composite или строкой composite_list: tracecontext, baggage, b3 (B3 Single Header), b3multi (B3 Multi Header). Для b3 и b3multi нужен пакет opentelemetry-propagator-b3: без него, как и для неизвестного имени, ОтелКонфигурационнаяФабрика.Создать выбрасывает исключение. Если секции propagator нет или в ней не задан ни один пропагатор, пропагация отключена (noop-пропагатор), как требует схема файла конфигурации; OTEL_PROPAGATORS при этом не читается.

Компоненты, которых нет в SDK (pull-экспортер, сэмплер или экспортер пользователя), разбор сохраняет как ОтелКонфигурацияКомпонента — имя и свойства из файла. ОтелКонфигурационнаяФабрика.Создать создаёт их зарегистрированными провайдерами компонентов, а без провайдера выбрасывает исключение: SDK не запускается с конфигурацией, которую не может выполнить (см. ОтелКонфигурационнаяФабрика, «Компоненты, которых нет в SDK»). Читатель pull разбор сохраняет как ОтелКонфигурацияPullЧитателя.

yaml

propagator:
  composite:
    - tracecontext:
    - baggage:
    - b3multi:

ИнтерфейсПроцессорЛогов

Интерфейс процессора записей лога (LogRecordProcessor) — методы, которые SDK вызывает у процессора.

Описание

Процессор логов получает каждую запись, которую логгер передаёт провайдеру в Записать, и решает, что с ней делать: передать экспортеру, отфильтровать, дополнить атрибутами. Встроенные реализации — ОтелПростойПроцессорЛогов, ОтелПакетныйПроцессорЛогов и ОтелКомпозитныйПроцессорЛогов. Свой процессор пишут, например, чтобы дополнять записи атрибутами или фильтровать их до встроенного процессора: SDK должен позволять пользовательские процессоры и обёртки над встроенными (спецификация, раздел LogRecordProcessor).

Интерфейс — класс библиотеки с методами-заглушками и аннотацией &Интерфейс библиотеки extends. Класс процессора объявляет, что реализует интерфейс, аннотацией &Реализует("ИнтерфейсПроцессорЛогов") на конструкторе ПриСозданииОбъекта и определяет экспортные методы с теми же именами: процедуру ПриПоявлении и функции Включен, СброситьБуфер, Закрыть. Ниже для каждого метода описано, когда SDK его вызывает и чего ожидает.

Регистрация процессора

Процессор регистрируется в провайдере логирования:

ДобавитьПроцессор построителя ОтелПостроительПровайдераЛогирования — при создании провайдера;
ДобавитьПроцессор провайдера ОтелПровайдерЛогирования — в работающий провайдер, например в провайдер автоконфигурации (ОтелSdk.ПровайдерЛогирования()): процессор получает записи со следующего вызова Записать;
второй параметр конструктора ОтелПровайдерЛогирования или массив процессоров ОтелКомпозитныйПроцессорЛогов.

Процессоры вызываются в порядке регистрации.

Проверка реализации

SDK реализацию не проверяет: ДобавитьПроцессор принимает любой объект, а аннотация &Реализует — объявление, которое во время работы не проверяется. Методы ищутся по имени при вызове, и ошибка реализации проявляется так:

нет ПриПоявлении — на каждой записи композитный процессор пишет в лог предупреждение, остальные процессоры запись получают;
нет Включен — процессор считается включённым;
нет СброситьБуфер или Закрыть — СброситьБуфер или Закрыть провайдера возвращают ошибку.

Проверить класс заранее, например в тесте, можно валидатором библиотеки extends: он бросает исключение, если класс, объявивший &Реализует("ИнтерфейсПроцессорЛогов"), не определяет какой-либо метод интерфейса или метод нельзя вызвать с числом параметров метода интерфейса (лишние параметры допустимы, если они необязательные). Так тесты SDK проверяют встроенные процессоры.

bsl

#Использовать extends

// Процессор - объект проверяемого класса
Валидатор = Новый ВалидаторРеализации();
Валидатор.ИнтерфейсыРеализованыКорректно(Процессор);

Методы

ПриПоявлении

Обрабатывает запись лога (OnEmit). Логгер вызывает метод через цепочку процессоров провайдера в Записать — синхронно, в потоке, который записал лог. При записи логов из нескольких потоков (фоновых заданий) метод вызывается одновременно, поэтому общее состояние процессора нужно защищать.

Запись изменяема (ReadWriteLogRecord): во время вызова процессор может её менять, например добавить атрибут через УстановитьАтрибут. Изменения видны процессорам, зарегистрированным после него (спецификация, раздел OnEmit). После прохода всей цепочки логгер фиксирует запись: сеттеры больше ничего не меняют, поэтому запись, сохранённую для обработки позже, можно только читать.
Не переприсваивайте параметры: новое значение ЗаписьЛога или Контекст получат и следующие процессоры.
Метод не должен блокироваться и бросать исключения (спецификация, раздел OnEmit): сбои обработки и экспорта пишите в лог. Исключение композитный процессор перехватывает и пишет в лог предупреждением, следующие процессоры запись получают.
Фильтровать записи нужно здесь: Записать не опрашивает Включен процессоров.
После закрытия провайдера логгеры записи не передают, но запись из другого потока, начатая до закрытия, может прийти уже после Закрыть процессора. Такую запись нужно игнорировать, как это делают встроенные процессоры (спецификация, раздел ShutDown).

Параметр	Тип	По умолчанию	Описание
`ЗаписьЛога`	`ОтелЗаписьЛога`	—	Запись лога
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`, `Неопределено`	`Неопределено`	Разрешённый контекст: переданный в `Логгер.Записать` или текущий контекст потока. Из него можно взять, например, текущий спан (`ОтелКонтекст.СпанИзКонтекста`)

Включен

Сообщает, будет ли процессор обрабатывать запись с такими параметрами (Enabled). Логгер вызывает метод из Логгер.Включен, если провайдер не закрыт и в нём есть процессоры. Процессоры опрашиваются по порядку до первого, вернувшего Истина; Логгер.Включен возвращает Ложь, только если все процессоры вернули Ложь.

Возвращайте Ложь, если запись с такими параметрами процессор отбросит, иначе Истина — в том числе при неопределённом состоянии, например пока не загружена конфигурация (спецификация, раздел Enabled процессора логов). Если метода Включен у процессора нет, композитный процессор считает процессор включённым, но реализуйте метод явно — так поведение не зависит от обработки ошибки вызова.
Не изменяйте переданные объекты. Логгер передаёт неизменяемый контекст и копию области, а композитный процессор даёт каждому процессору свои копии параметров: переприсваивание параметра не видно ни следующим процессорам, ни вызывающему.
Включен не заменяет фильтрацию в ПриПоявлении: вызывать его перед Записать необязательно. Процессор-обёртка может передать Включен вложенному процессору, но в ПриПоявлении не должен вызывать Включен вложенного — фильтрует сам ПриПоявлении.
Метод, который бросает исключение или отсутствует, означает «процессор включён».

Параметр	Тип	По умолчанию	Описание
`Контекст`	`ФиксированноеСоответствие`, `Неопределено`	`Неопределено`	Контекст, переданный в `Логгер.Включен`, или текущий контекст потока
`ОбластьИнструментирования`	`ОтелОбластьИнструментирования`	`Неопределено`	Копия области логгера или области, переданной в `Логгер.Включен`
`СтепеньСерьезности`	`Число`	`0`	Номер серьезности, переданный в `Логгер.Включен`; `0` — не указан
`ИмяСобытия`	`Строка`	`""`	Имя события, переданное в `Логгер.Включен`; `""` — не указано

Возвращает: Булево — Истина, если процессор обработает запись с такими параметрами

СброситьБуфер

Как можно скорее завершает обработку записей, полученных до вызова (ForceFlush): например, экспортирует накопленные записи и сбрасывает буфер экспортера (спецификация, раздел ForceFlush процессора логов). Срок важнее полноты: процессор должен уложиться в таймаут, даже если часть записей не успеет уйти.

Вызывается из СброситьБуфер и ПринудительноВыгрузитьСРезультатом провайдера (и из ОтелSdk.СброситьБуфер). Провайдер вызывает метод у каждого процессора — даже после исключения в предыдущем и после истечения срока — и передаёт время, оставшееся до общего срока (после срока — 1 мс). Если провайдеру передан таймаут 0, метод вызывается без параметра, а композитный процессор передаёт таймаут всегда, поэтому параметр ТаймаутМс нужен и должен быть необязательным, как в интерфейсе.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Срок в миллисекундах, `0` — без ограничения

Возвращает: ОтелРезультатЭкспорта — ОтелРезультатыЭкспорта.Успех(), Ошибка() или Таймаут(). Провайдер сводит результаты процессоров: ошибка, если хотя бы один вернул ошибку или Ложь либо бросил исключение; иначе таймаут; иначе успех (Неопределено — успех). Композитный процессор значение без метода Успешно (например, Булево) считает ошибкой

Закрыть

Завершает работу процессора (Shutdown): обрабатывает накопленные записи — Закрыть должен включать эффект СброситьБуфер, — освобождает ресурсы (встроенные процессоры закрывают свой экспортер) и больше не принимает записи. Метод должен уложиться в таймаут и сообщить, успешно ли закрытие, был ли сбой или истёк срок (спецификация, раздел ShutDown).

Вызывается из Закрыть провайдера (и из ОтелSdk.Закрыть) один раз: повторное закрытие провайдера процессоры не вызывает. Провайдер вызывает метод у каждого процессора — даже после исключения в предыдущем и после истечения срока: тогда процессор получает 1 мс и должен завершиться без ожидания. Если провайдеру передан таймаут 0, метод вызывается без параметра, поэтому параметр ТаймаутМс должен быть необязательным.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Срок в миллисекундах, `0` — без ограничения

Возвращает: ОтелРезультатЗакрытия — ОтелРезультатыЗакрытия.Успех(), Ошибка(Описание) или Таймаут(). Неопределено провайдер считает успехом, Ложь — ошибкой, исключение — ошибкой с его описанием

Пример

Процессор-обёртка, который передаёт вложенному процессору только записи не ниже заданной серьезности:

bsl

// Файл ФильтрПоСерьезности.os
Перем Вложенный;
Перем МинимальнаяСерьезность;

Процедура ПриПоявлении(ЗаписьЛога, Контекст = Неопределено) Экспорт
    // Записать не опрашивает Включен: фильтровать запись нужно здесь
    Если НижеМинимальной(ЗаписьЛога.НомерСерьезности()) Тогда
        Возврат;
    КонецЕсли;
    Вложенный.ПриПоявлении(ЗаписьЛога, Контекст);
КонецПроцедуры

Функция Включен(Контекст = Неопределено, ОбластьИнструментирования = Неопределено,
        СтепеньСерьезности = 0, ИмяСобытия = "") Экспорт
    Если НижеМинимальной(СтепеньСерьезности) Тогда
        Возврат Ложь;
    КонецЕсли;
    Возврат Вложенный.Включен(Контекст, ОбластьИнструментирования, СтепеньСерьезности, ИмяСобытия);
КонецФункции

Функция СброситьБуфер(ТаймаутМс = 0) Экспорт
    Возврат Вложенный.СброситьБуфер(ТаймаутМс);
КонецФункции

Функция Закрыть(ТаймаутМс = 0) Экспорт
    Возврат Вложенный.Закрыть(ТаймаутМс);
КонецФункции

// Серьезность 0 не указана: такую запись фильтр не отбрасывает
Функция НижеМинимальной(Серьезность)
    Возврат Серьезность <> 0 И Серьезность < МинимальнаяСерьезность;
КонецФункции

&Реализует("ИнтерфейсПроцессорЛогов")
Процедура ПриСозданииОбъекта(НовыйВложенный, НоваяМинимальнаяСерьезность)
    Вложенный = НовыйВложенный;
    МинимальнаяСерьезность = НоваяМинимальнаяСерьезность;
КонецПроцедуры

Регистрация:

bsl

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "ФильтрПоСерьезности.os"),
    "ФильтрПоСерьезности");

Экспортер = Новый ОтелЭкспортерЛогов(Новый ОтелHttpТранспорт("http://localhost:4318"));
Фильтр = Новый ФильтрПоСерьезности(Новый ОтелПростойПроцессорЛогов(Экспортер),
    ОтелСтепеньСерьезности.Warn());

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .ДобавитьПроцессор(Фильтр)
    .Построить();

Логгер = Провайдер.ПолучитьЛоггер("my-library");
Логгер.Включен(, , ОтелСтепеньСерьезности.Debug()); // Ложь: Debug ниже Warn

Провайдер.Закрыть();

См. также

ОтелЗаписьЛога

Запись лога (LogRecord) — объект, содержащий все поля одной записи лога.

Описание

ОтелЗаписьЛога реализует спецификацию OpenTelemetry LogRecord / ReadWriteLogRecord. Содержит: тело, серьезность, атрибуты, время, имя события, контекст трассировки, ресурс и scope.

После вызова Логгер.Записать() запись фиксируется (Зафиксировать()) и становится неизменяемой — все сеттеры превращаются в no-op.

Уважает лимиты атрибутов из ОтелЛимитыЗаписейЛога: атрибуты сверх лимита отбрасываются, длинные строковые значения усекаются.

Конструктор

Параметр	Тип	По умолчанию	Описание
`ЛимитыЗаписейЛога`	`ОтелЛимитыЗаписейЛога`	`Неопределено`	Лимиты записей лога (иначе 128 атрибутов, без ограничения длины)

Методы — Геттеры

Время

Возвращает время записи лога в наносекундах Unix epoch.

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

ВремяНаблюдения

Возвращает время наблюдения записи лога в наносекундах Unix epoch.

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

НомерСерьезности

Возвращает номер серьезности (SeverityNumber).

Возвращает: Число — 0 (SEVERITY_NUMBER_UNSPECIFIED), если серьезность не задана

ТекстСерьезности

Возвращает текст серьезности (SeverityText).

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

Тело

Возвращает тело записи лога.

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

Атрибуты

Возвращает копию атрибутов записи лога. Изменение копии не меняет запись: атрибуты записываются через УстановитьАтрибут, который применяет лимиты ОтелЛимитыЗаписейЛога.

Возвращает: ОтелАтрибуты

ИдТрассировки

Возвращает идентификатор трассировки для корреляции.

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

ИдСпана

Возвращает идентификатор спана для корреляции.

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

ФлагиТрассировки

Возвращает флаги трассировки (TraceFlags).

Возвращает: Число

Ресурс

Возвращает ресурс, описывающий источник телеметрии.

Возвращает: ОтелРесурс

ОбластьИнструментирования

Возвращает область инструментирования (InstrumentationScope).

Возвращает: ОтелОбластьИнструментирования

КоличествоОтброшенныхАтрибутов

Возвращает количество атрибутов, отброшенных из-за превышения лимита.

Возвращает: Число

ИмяСобытия

Возвращает имя события (EventName) по спецификации.

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

ИнформацияОбИсключении

Возвращает информацию об исключении (если установлена).

Возвращает: ИнформацияОбОшибке, Неопределено

Методы — Сеттеры (fluent API)

Все сеттеры возвращают ОтелЗаписьЛога (ЭтотОбъект) для цепочки вызовов. После Зафиксировать() становятся no-op.

УстановитьСерьезность

Устанавливает серьезность по номеру из ОтелСтепеньСерьезности. Если текст серьезности не задан явно через УстановитьТекстСерьезности, в ТекстСерьезности подставляется короткое имя номера.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Номер серьезности (см. ОтелСтепеньСерьезности)

УстановитьТекстСерьезности

Устанавливает произвольный текст серьезности независимо от номера. Явно заданный текст не заменяется последующими вызовами УстановитьСерьезность.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	Текст серьезности

УстановитьТело

Устанавливает тело записи. Принимает строку, число, булево, массив или соответствие (AnyValue).

Параметр	Тип	По умолчанию	Описание
`Значение`	`Произвольный`	—	Содержимое лога

УстановитьАтрибут

Устанавливает атрибут записи лога. Уважает лимиты: атрибуты сверх лимита отбрасываются, строки длиннее лимита усекаются.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Имя атрибута
`Значение`	`Произвольный`	—	Значение атрибута

УдалитьАтрибут

Удаляет атрибут записи лога (ReadWriteLogRecord MUST поддерживать удаление).

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Имя атрибута

УстановитьКонтекстТрассировки

Устанавливает контекст трассировки для корреляции лога с трассировкой.

Параметр	Тип	По умолчанию	Описание
`НовыйИдТрассировки`	`Строка`	—	Идентификатор трассировки
`НовыйИдСпана`	`Строка`	—	Идентификатор спана

УстановитьФлагиТрассировки

Устанавливает флаги трассировки.

Параметр	Тип	По умолчанию	Описание
`Флаги`	`Число`	—	Флаги трассировки

УстановитьИмяСобытия

Устанавливает имя события (EventName) по спецификации.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	Имя события

УстановитьВремя

Устанавливает время записи лога в наносекундах Unix epoch.

Параметр	Тип	По умолчанию	Описание
`ВремяНаносекунды`	`Строка`	—	Время в наносекундах

УстановитьВремяНаблюдения

Устанавливает время наблюдения записи лога в наносекундах Unix epoch.

Параметр	Тип	По умолчанию	Описание
`ВремяНаносекунды`	`Строка`	—	Время наблюдения в наносекундах

УстановитьИсключение

Устанавливает информацию об исключении. SDK автоматически извлечёт атрибуты exception.type, exception.message, exception.stacktrace. Атрибут, уже заданный в записи, SDK не перезаписывает.

exception.type — машинный код ошибки библиотеки errors (ДиагностикаОшибок.КодОшибки, в том числе через обертки ФабрикаОшибок.Обернуть и ФабрикаОшибок.ОбернутьКонтекстом). У нативной ошибки OneScript без кода тип определяет классификатор native-errors: numeric.division_by_zero, json.reader.not_open, network.connection.refused и т.п. У нераспознанной ошибки без кода атрибут не заполняется: по семантическим соглашениям он обязателен, только если нет exception.message. Если exception.type уже задан в записи, ошибка не классифицируется — классификация стоит порядка 1–2 мс.

exception.stacktrace — описание ошибки и стек вызовов OneScript, включая цепочку причин (Caused by:), в том же формате, что у события исключения спана (ОтелУтилиты.СтекВызововИсключения).

Параметр	Тип	По умолчанию	Описание
`Значение`	`ИнформацияОбОшибке`	—	Информация об исключении

Зафиксировать

Фиксирует запись лога, делая её неизменяемой. Автоматически вызывается в Логгер.Записать().

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

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

УстановитьРесурс — устанавливает ресурс записи: логгер в Записать передаёт ресурс провайдера;
УстановитьОбластьИнструментирования — устанавливает область инструментирования записи: логгер в Записать передаёт свою область.

Пример

bsl

Запись = Логгер.СоздатьЗаписьЛога();
Запись
    .УстановитьСерьезность(ОтелСтепеньСерьезности.Error())
    .УстановитьТело("Критическая ошибка обработки заказа")
    .УстановитьАтрибут("order.id", "12345")
    .УстановитьАтрибут("user.id", "42")
    .УстановитьИмяСобытия("order.failed");
Логгер.Записать(Запись);

// С исключением
Попытка
    ОбработатьЗаказ();
Исключение
    Запись = Логгер.СоздатьЗаписьЛога();
    Запись
        .УстановитьСерьезность(ОтелСтепеньСерьезности.Error())
        .УстановитьТело("Ошибка обработки заказа")
        .УстановитьИсключение(ИнформацияОбОшибке());
    Логгер.Записать(Запись);
КонецПопытки;

ОтелКомпозитныйПроцессорЛогов

Композитный процессор логов — цепочка процессоров записей лога, которая работает как один процессор.

Описание

Передаёт каждый вызов процессорам цепочки в порядке добавления. Реализует ИнтерфейсПроцессорЛогов, поэтому регистрируется в провайдере как обычный процессор — например, чтобы передать несколько процессоров конструктору ОтелПровайдерЛогирования, который принимает один процессор.

Провайдер логирования и сам хранит свои процессоры в композитном процессоре: ДобавитьПроцессор провайдера добавляет процессор в эту цепочку, а логгеры передают ей записи. Сброс буфера и закрытие провайдер выполняет сам, вызывая каждый процессор цепочки напрямую (см. СброситьБуфер и Закрыть провайдера).

Список процессоров изменяется копированием: ДобавитьПроцессор создаёт новый список, поэтому цепочка обходится без блокировки, а обход, уже начатый в другом потоке или в самом процессоре, продолжается по прежнему списку.

Конструктор

bsl

Новый ОтелКомпозитныйПроцессорЛогов(Процессоры)

Параметр	Тип	По умолчанию	Описание
`Процессоры`	`Массив`	—	Процессоры логов в порядке вызова. Массив копируется: его изменение после создания цепочку не меняет

Методы

ДобавитьПроцессор

Добавляет процессор в конец цепочки. Обход цепочки, уже начатый в другом потоке или в самом процессоре, продолжается по прежнему списку: новый процессор получают следующие вызовы. Объект не проверяется: как проявляется процессор без нужных методов, см. ИнтерфейсПроцессорЛогов.

Параметр	Тип	По умолчанию	Описание
`Процессор`	`Произвольный`	—	Процессор логов

Методы процессора

Методы ИнтерфейсПроцессорЛогов. Их вызывает провайдер логирования, в который добавлен композитный процессор: ПриПоявлении — логгер в Записать, Включен — Включен логгера, СброситьБуфер — СброситьБуфер и ПринудительноВыгрузитьСРезультатом провайдера, Закрыть — Закрыть провайдера. Приложению вызывать их не нужно, если композитный процессор добавлен в провайдер.

ПриПоявлении

Передаёт запись лога каждому процессору цепочки (OnEmit). Все процессоры получают один и тот же объект записи: изменения, сделанные одним процессором, видны следующим (спецификация, раздел OnEmit). Параметры не копируются: если процессор переприсвоит параметр (ЗаписьЛога или Контекст), новое значение получат и следующие процессоры. Исключение процессора записывается в лог предупреждением и не прерывает цепочку.

Параметр	Тип	По умолчанию	Описание
`ЗаписьЛога`	`ОтелЗаписьЛога`	—	Запись лога
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`, `Неопределено`	`Неопределено`	Разрешённый контекст: переданный в `Логгер.Записать` или текущий контекст потока

Включен

Проверяет, будет ли хотя бы один процессор цепочки обрабатывать запись с такими параметрами (Enabled). Процессоры опрашиваются по порядку до первого, вернувшего Истина, — остальные не опрашиваются. Процессор, у которого Включен бросает исключение (в том числе если метода нет), считается включённым.

Каждый процессор получает свои копии параметров: переприсваивание параметра одним процессором не видно следующим и вызывающему.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`, `Неопределено`	`Неопределено`	Контекст
`ОбластьИнструментирования`	`ОтелОбластьИнструментирования`	`Неопределено`	Область инструментирования логгера
`СтепеньСерьезности`	`Число`	`0`	Номер серьезности записи, `0` — не указан
`ИмяСобытия`	`Строка`	`""`	Имя события

Возвращает: Булево — Истина, если хотя бы один процессор вернул Истина или бросил исключение; Ложь, если процессоров нет или все вернули Ложь

СброситьБуфер

Сбрасывает буфер процессоров цепочки по порядку (ForceFlush). Каждый процессор получает время, оставшееся до общего срока. Если срок истёк раньше, чем дошла очередь до следующего процессора, метод сразу возвращает таймаут, и оставшиеся процессоры не вызываются. Исключение процессора записывается в лог предупреждением.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Общий срок в миллисекундах, `0` — без ограничения

Возвращает: ОтелРезультатЭкспорта — таймаут, если срок истёк до вызова очередного процессора; иначе неуспешный результат последнего процессора, сообщившего о сбое (исключение процессора — ошибка); иначе успех. Результат процессора Неопределено считается успехом, а значение без метода Успешно (например, Булево) — ошибкой

Закрыть

Закрывает все процессоры цепочки (Shutdown) в пределах общего срока. Закрыть вызывается у каждого процессора — даже после исключения в предыдущем и после истечения срока: тогда процессор получает 1 мс и должен завершиться без ожидания. При ТаймаутМс = 0 Закрыть процессоров вызывается без параметра, и каждый процессор применяет свой таймаут по умолчанию. Неуспешный итог записывается в лог предупреждением.

Своего признака закрытия у композитного процессора нет: повторный вызов снова вызывает Закрыть процессоров, а ПриПоявлении после закрытия по-прежнему передаёт записи процессорам — встроенные процессоры после своего Закрыть записи игнорируют.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Общий срок в миллисекундах, `0` — без общего срока

Возвращает: ОтелРезультатЗакрытия — ошибка, если хотя бы один процессор вернул ошибку или Ложь либо бросил исключение (описания перечислены через ; ); иначе таймаут, если истёк срок или процессор сообщил о таймауте; иначе успех

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

ЕстьПроцессоры — есть ли в цепочке хотя бы один процессор: без процессоров Включен логгера возвращает Ложь;
Процессоры — копия списка процессоров цепочки: по ней провайдер сбрасывает буфер и закрывает процессоры.

Пример

bsl

// ПакетныйПроцессор - пакетный процессор логов (см. ОтелПакетныйПроцессорЛогов),
// ОтладочныйЭкспортер - второй экспортер логов
Процессоры = Новый Массив();
Процессоры.Добавить(ПакетныйПроцессор);
Процессоры.Добавить(Новый ОтелПростойПроцессорЛогов(ОтладочныйЭкспортер));
Процессор = Новый ОтелКомпозитныйПроцессорЛогов(Процессоры);

// Конструктор провайдера принимает один процессор
Провайдер = Новый ОтелПровайдерЛогирования(Ресурс, Процессор);
Логгер = Провайдер.ПолучитьЛоггер("my-library", "1.0.0");

// Провайдер закрывает композитный процессор, а тот - процессоры цепочки
Провайдер.Закрыть();

См. также

ОтелЛимитыЗаписейЛога

Лимиты записей лога (LogLimits) — настройки ограничений атрибутов.

Описание

ОтелЛимитыЗаписейЛога задаёт ограничения на количество атрибутов и длину их строковых значений в ОтелЗаписьЛога. Используется при создании провайдера через ОтелПостроительПровайдераЛогирования.

Аналог Java SDK: io.opentelemetry.sdk.logs.LogLimits.

По умолчанию: максимум 128 атрибутов, без ограничения длины строковых значений, глубина значения не больше 64. Лимит длины действует и на строки внутри массивов, вложенный массив глубже лимита заменяется пустым значением.

Методы

МаксАтрибутов

Возвращает максимальное количество атрибутов записи лога.

Возвращает: Число

МаксДлинаЗначенияАтрибута

Возвращает максимальную длину значения строкового атрибута.

Возвращает: Число, Неопределено — лимит; Неопределено (по умолчанию) — без ограничения, 0 — строки усекаются до пустых

МаксГлубинаЗначенияАтрибута

Возвращает максимальную глубину значения атрибута. Глубина верхнего значения — 1.

Возвращает: Число — по умолчанию 64

УстановитьМаксАтрибутов

Устанавливает максимальное количество атрибутов записи лога.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Максимальное количество атрибутов

Возвращает: ОтелЛимитыЗаписейЛога — ЭтотОбъект для цепочки вызовов

УстановитьМаксДлинаЗначенияАтрибута

Устанавливает максимальную длину значения строкового атрибута.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`, `Неопределено`	—	Максимальная длина; `Неопределено` — без ограничения, `0` — нулевой лимит

Возвращает: ОтелЛимитыЗаписейЛога — ЭтотОбъект для цепочки вызовов

УстановитьМаксГлубинаЗначенияАтрибута

Устанавливает максимальную глубину значения атрибута.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Максимальная глубина (глубина верхнего значения — 1)

Возвращает: ОтелЛимитыЗаписейЛога — ЭтотОбъект для цепочки вызовов

Пример

bsl

Лимиты = Новый ОтелЛимитыЗаписейЛога()
    .УстановитьМаксАтрибутов(256)
    .УстановитьМаксДлинаЗначенияАтрибута(2048);

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .УстановитьЛимитыЗаписейЛога(Лимиты)
    .Построить();

ОтелЛоггер

Логгер (Logger) — инструмент для создания и отправки записей лога.

Описание

ОтелЛоггер реализует спецификацию OpenTelemetry Logger API. Создаётся через ОтелПровайдерЛогирования. Логгер привязан к ОтелОбластьИнструментирования и делегирует записи цепочке процессоров провайдера.

Все публичные методы потокобезопасны.

Методы

СоздатьЗаписьЛога

Создаёт новую запись лога с лимитами из провайдера.

Возвращает: ОтелЗаписьЛога

Включен

Проверяет, включён ли логгер для заданных параметров.

Вызывать Включен необязательно: он не требуется перед Записать, которая сама отбрасывает запись без провайдера, после его закрытия и без процессоров. Включен процессоров Записать не опрашивает: запись получает ПриПоявлении каждого процессора. Включен — оптимизация, полезная, только когда построение записи дорогое — например, тело или атрибуты вычисляются по данным из базы: тогда можно сначала вызвать Включен и пропустить эту работу при Ложь. Дешёвую запись можно сразу передавать в Записать.

Важно: результат не постоянен и может меняться со временем (регистрация процессоров, закрытие провайдера): сохранённое значение может устареть.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Явный контекст (иначе текущий контекст потока)
`ОбластьИнструментирования`	`ОтелОбластьИнструментирования`	`Неопределено`	Scope (иначе scope логгера)
`СтепеньСерьезности`	`Число`	`0`	Номер серьезности для фильтрации
`ИмяСобытия`	`Строка`	`""`	Имя события для фильтрации

Возвращает: Булево — Истина, если логгер может обрабатывать записи

Записать

Отправляет запись лога. Устанавливает scope, resource и trace context, затем передаёт запись процессору. После вызова запись становится неизменяемой (Зафиксировать()).

Параметр	Тип	По умолчанию	Описание
`ЗаписьЛога`	`ОтелЗаписьЛога`	—	Запись лога для отправки
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Явный контекст для trace correlation

ОбластьИнструментирования

Возвращает область инструментирования логгера.

Возвращает: ОтелОбластьИнструментирования

Пример

bsl

Логгер = Провайдер.ПолучитьЛоггер("мой-сервис", "1.0.0");

// Дешёвая запись передаётся сразу, без Включен()
Запись = Логгер.СоздатьЗаписьЛога();
Запись
    .УстановитьСерьезность(ОтелСтепеньСерьезности.Info())
    .УстановитьТело("Операция завершена")
    .УстановитьАтрибут("user.id", "42");
Логгер.Записать(Запись);

// Включен() экономит дорогое построение записи
Если Логгер.Включен(, , ОтелСтепеньСерьезности.Debug()) Тогда
    Запись = Логгер.СоздатьЗаписьЛога();
    Запись
        .УстановитьСерьезность(ОтелСтепеньСерьезности.Debug())
        .УстановитьТело(ПостроитьОтчетОСостоянии()); // дорогое вычисление
    Логгер.Записать(Запись);
КонецЕсли;

ОтелПакетныйПроцессорЛогов

Пакетный процессор записей логов (BatchLogRecordProcessor) по спецификации OpenTelemetry.

Описание

Буферизует записи лога и отправляет их экспортеру асинхронно, партиями. Thin facade — вся логика буферизации реализована в ОтелБазовыйПакетныйПроцессор.

Реализует ИнтерфейсПроцессорЛогов.

Важно: Процессор хранит переданный объект ОтелЗаписьЛога as-is и обрабатывает его асинхронно. Если вызывающая сторона продолжает модифицировать запись после ПриПоявлении() — возможны гонки данных. Передавайте клон или не модифицируйте запись после передачи.

Создание

Конструктор без параметров. Процессор собирается через ПостроительНаследника из ОтелБазовыйПакетныйПроцессор, которому передаются настройки:

Параметр	Тип	По умолчанию	Описание
`Экспортер`	`Произвольный`	—	Экспортер логов
`ИмяСигнала`	`Строка`	—	Имя сигнала для лога: `"logs"`
`МаксРазмерБуфера`	`Число`	`2048`	Максимальный размер очереди
`МаксРазмерПакета`	`Число`	`512`	Максимальный размер пакета; размер больше размера очереди ограничивается размером очереди
`ИнтервалЭкспортаМс`	`Число`	`1000`	Интервал фонового экспорта в миллисекундах (значение по умолчанию спецификации для логов)
`ТаймаутЭкспортаМс`	`Число`	`30000`	Таймаут экспорта в миллисекундах

Записи экспортирует фоновое задание: оно запускается с первой записью и отправляет пакет, как только накопился полный пакет или истёк интервал экспорта. ПриПоявлении не ждёт отправку даже при заполнении пакета. ЗапуститьФоновыйЭкспорт() запускает задание заранее; вызывать его не обязательно.

Запись, пришедшая в полную очередь, отбрасывается. При извлечении следующего пакета в лог oscript.lib.opentelemetry.logs пишется предупреждение с числом записей, отброшенных с прошлого пакета.

Методы

ПриПоявлении

Добавляет запись лога в буфер (OnEmit) и возвращается, не дожидаясь экспорта. Буфер обрабатывается фоновым заданием.

Параметр	Тип	По умолчанию	Описание
`ЗаписьЛога`	`ОтелЗаписьЛога`	—	Запись лога (не должна модифицироваться после передачи)
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Разрешённый контекст

Включен

Проверяет, будет ли процессор обрабатывать запись. Всегда возвращает Истина. Реализация не мутирует переданные объекты.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Явный контекст
`ОбластьИнструментирования`	`ОтелОбластьИнструментирования`	`Неопределено`	Scope логгера
`СтепеньСерьезности`	`Число`	`0`	Номер серьезности
`ИмяСобытия`	`Строка`	`""`	Имя события

Возвращает: Булево

СброситьБуфер

Принудительно экспортирует все записи из буфера.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЭкспорта — ошибка, если экспорт пакета не удался; таймаут при истечении срока

Закрыть

Завершает работу процессора: останавливает фоновый экспорт, экспортирует оставшиеся в буфере записи и закрывает экспортер. Все три шага укладываются в один общий срок; экспортер закрывается и после сбоя или таймаута финального экспорта. После вызова ПриПоявлении игнорирует новые записи; повторный вызов возвращает ошибку «Процессор закрыт».

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЗакрытия — ошибка финального экспорта или закрытия экспортера; иначе таймаут, если истёк срок; иначе успех

Пример

bsl

Экспортер = Новый ОтелЭкспортерЛогов(Новый ОтелHttpТранспорт("http://localhost:4318"));

Базовый = Новый ОтелБазовыйПакетныйПроцессор(Экспортер, "logs", 2048, 512, 1000);
Процессор = Новый ПостроительНаследника(Новый ОтелПакетныйПроцессорЛогов(), Базовый).Построить();
Процессор.ЗапуститьФоновыйЭкспорт();

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Процессор)
    .Построить();

ОтелПостроительЛоггера

Построитель логгера (LoggerBuilder) — получение логгера с версией, адресом схемы и атрибутами области.

Описание

Задаёт, кроме имени инструментирующей библиотеки, её версию, адрес схемы телеметрии (schema URL) и атрибуты области инструментирования (InstrumentationScope) цепочкой вызовов. Аналог Java SDK: LoggerProvider.loggerBuilder("name").

Построитель возвращает метод ПостроительЛоггера(ИмяБиблиотеки) провайдера логирования (ОтелПровайдерЛогирования) или SDK (ОтелSdk — построитель его провайдера логирования). Имя библиотеки задаётся при создании построителя, остальные параметры необязательны: по умолчанию версия и адрес схемы — пустые строки, атрибутов области нет.

Построить получает логгер у провайдера (ПолучитьЛоггер) с заданными параметрами, поэтому действует кэш провайдера: для той же области инструментирования — имени, версии, адреса схемы и атрибутов — возвращается тот же логгер. После закрытия провайдера Построить возвращает логгер, который отбрасывает записи.

Методы

УстановитьВерсию

Устанавливает версию инструментирующей библиотеки.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	Версия библиотеки, например `"1.0.0"`

Возвращает: ОтелПостроительЛоггера — ЭтотОбъект для цепочки вызовов

УстановитьАдресСхемы

Устанавливает адрес схемы телеметрии (schema URL) области инструментирования.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	URL схемы

Возвращает: ОтелПостроительЛоггера — ЭтотОбъект для цепочки вызовов

УстановитьАтрибутыОбласти

Устанавливает атрибуты области инструментирования. Атрибуты входят в идентичность области: логгеры одной библиотеки с разными атрибутами — разные логгеры. Область копирует атрибуты при создании логгера, поэтому изменение объекта атрибутов после Построить логгер не меняет.

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелАтрибуты`	—	Атрибуты области инструментирования

Возвращает: ОтелПостроительЛоггера — ЭтотОбъект для цепочки вызовов

Построить

Создаёт логгер с заданными параметрами или возвращает уже созданный логгер той же области инструментирования. Пустое имя библиотеки или Неопределено допускается: провайдер пишет предупреждение в лог и создаёт логгер с этим именем.

Возвращает: ОтелЛоггер

Пример

bsl

// Провайдер - ОтелПровайдерЛогирования
АтрибутыОбласти = Новый ОтелАтрибуты();
АтрибутыОбласти.Установить("module", "orders");

Логгер = Провайдер.ПостроительЛоггера("my-library")
    .УстановитьВерсию("1.0.0")
    .УстановитьАдресСхемы("https://opentelemetry.io/schemas/1.26.0")
    .УстановитьАтрибутыОбласти(АтрибутыОбласти)
    .Построить();

// Тот же логгер: область инструментирования совпадает
ТотЖеЛоггер = Провайдер.ПостроительЛоггера("my-library")
    .УстановитьВерсию("1.0.0")
    .УстановитьАдресСхемы("https://opentelemetry.io/schemas/1.26.0")
    .УстановитьАтрибутыОбласти(АтрибутыОбласти)
    .Построить();

// Через SDK (Сдк - ОтелSdk)
Логгер = Сдк.ПостроительЛоггера("my-library")
    .УстановитьВерсию("1.0.0")
    .Построить();

См. также

ОтелПостроительПровайдераЛогирования

Построитель провайдера логирования (SdkLoggerProviderBuilder) с fluent API.

Описание

Используется для пошаговой конфигурации ОтелПровайдерЛогирования: задаёт ресурс, процессоры логов и лимиты записей. Аналог Java SDK: SdkLoggerProvider.builder().

Методы

УстановитьРесурс

Устанавливает ресурс, описывающий источник телеметрии.

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелРесурс`	—	Ресурс телеметрии

Возвращает: ОтелПостроительПровайдераЛогирования — ЭтотОбъект для цепочки вызовов

ДобавитьПроцессор

Добавляет процессор логов. Аналог Java SDK: SdkLoggerProviderBuilder.addLogRecordProcessor(processor).

Параметр	Тип	По умолчанию	Описание
`Процессор`	`Произвольный`	—	Процессор логов: встроенный или свой, см. ИнтерфейсПроцессорЛогов

Возвращает: ОтелПостроительПровайдераЛогирования — ЭтотОбъект для цепочки вызовов

УстановитьЛимитыЗаписейЛога

Устанавливает лимиты записей лога. Аналог Java SDK: SdkLoggerProviderBuilder.setLogLimits(logLimits).

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелЛимитыЗаписейЛога`	—	Лимиты записей лога

Возвращает: ОтелПостроительПровайдераЛогирования — ЭтотОбъект для цепочки вызовов

Построить

Создаёт экземпляр провайдера логирования с заданными параметрами.

Возвращает: ОтелПровайдерЛогирования

Пример

bsl

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Новый ОтелПростойПроцессорЛогов(Экспортер))
    .УстановитьЛимитыЗаписейЛога(
        Новый ОтелЛимитыЗаписейЛога()
            .УстановитьМаксАтрибутов(256)
    )
    .Построить();

ОтелПровайдерЛогирования

Провайдер логирования (LoggerProvider) — центральная точка управления логгерами и процессорами.

Описание

ОтелПровайдерЛогирования реализует спецификацию OpenTelemetry LoggerProvider. Хранит кэш логгеров по идентичности области (имя библиотеки, версия, адрес схемы и атрибуты scope) и делегирует записи логов цепочке процессоров. Все публичные методы потокобезопасны.

Рекомендуется создавать через ОтелПостроительПровайдераЛогирования.

Конструктор

Параметр	Тип	По умолчанию	Описание
`НовыйРесурс`	`ОтелРесурс`	`Неопределено`	Ресурс, описывающий источник телеметрии (по умолчанию пустой `ОтелРесурс`)
`Процессор`	`Произвольный`	`Неопределено`	Процессор записей логов
`ЛимитыЗаписейЛога`	`ОтелЛимитыЗаписейЛога`	`Неопределено`	Лимиты записей лога

Методы

ПостроительЛоггера

Создаёт построитель логгера (LoggerBuilder).

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки

Возвращает: ОтелПостроительЛоггера

ПолучитьЛоггер

Создаёт или возвращает из кэша логгер для указанной библиотеки. После Закрыть() возвращает рабочий no-op логгер.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки
`АтрибутыОбласти`	`ОтелАтрибуты`	`Неопределено`	Атрибуты InstrumentationScope
`АдресСхемы`	`Строка`	`""`	URL схемы телеметрии

Возвращает: ОтелЛоггер

ДобавитьПроцессор

Добавляет процессор логов в цепочку.

Параметр	Тип	По умолчанию	Описание
`Процессор`	`Произвольный`	—	Процессор логов: встроенный или свой, см. ИнтерфейсПроцессорЛогов

Ресурс

Возвращает ресурс провайдера.

Возвращает: ОтелРесурс

СброситьБуфер

Принудительно отправляет все накопленные данные через процессоры. СброситьБуфер вызывается у каждого процессора, даже если предыдущий бросил исключение; все процессоры укладываются в общий срок — каждому передаётся оставшееся время.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЭкспорта — ошибка, если хотя бы один процессор сообщил о сбое или бросил исключение; иначе таймаут, если истёк срок или процессор сообщил о таймауте; иначе успех

Закрыть

Завершает работу провайдера (Shutdown). Закрыть вызывается у каждого процессора в пределах общего срока — даже после исключения в предыдущем и после истечения срока (тогда процессор получает 1 мс и завершается без ожидания). Идемпотентен: повторный вызов возвращает успех.

После закрытия ПолучитьЛоггер() возвращает no-op логгер, логгеры, полученные раньше, отбрасывают записи и возвращают Ложь из Включен, а ПринудительноВыгрузитьСРезультатом возвращает ошибку «Провайдер логирования закрыт».

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут операции в миллисекундах

Возвращает: ОтелРезультатЗакрытия — ошибка, если хотя бы один процессор вернул ошибку или бросил исключение (описания ошибок перечислены через ; ); иначе таймаут, если истёк срок или процессор сообщил о таймауте; иначе успех

ПринудительноВыгрузитьСРезультатом

Принудительно отправляет все данные и возвращает результат в формате OTel SDK.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут операции в миллисекундах

Возвращает: ОтелРезультатЗакрытия

СброситьБуферАсинхронно

Асинхронно сбрасывает буфер. Аналог Java SDK: CompletableResultCode forceFlush().

Возвращает: Обещание

ЗакрытьАсинхронно

Асинхронно завершает работу провайдера. Аналог Java SDK: CompletableResultCode shutdown().

Возвращает: Обещание

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

Процессор — композитный процессор (ОтелКомпозитныйПроцессорЛогов) с цепочкой процессоров провайдера: логгер передаёт ему записи и опрашивает его в Включен;
ЛимитыЗаписейЛога — лимиты записей лога, заданные провайдеру (Неопределено, если не заданы): логгер передаёт их новой записи в СоздатьЗаписьЛога;
Закрыт — Истина с начала первого вызова Закрыть, ещё до закрытия процессоров: по нему логгер отбрасывает записи закрытого провайдера.

Пример

bsl

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Новый ОтелПростойПроцессорЛогов(Экспортер))
    .Построить();

Логгер = Провайдер.ПолучитьЛоггер("мой-сервис", "1.0.0");

// После завершения работы
Провайдер.Закрыть();

ОтелПростойПроцессорЛогов

Простой процессор записей логов (SimpleLogRecordProcessor) по спецификации OpenTelemetry.

Описание

Синхронно передаёт каждую запись лога экспортеру в момент вызова ПриПоявлении(). Аналог ОтелПростойПроцессорСпанов для подсистемы логирования. Потокобезопасен — доступ к экспортеру защищён блокировкой.

Реализует ИнтерфейсПроцессорЛогов.

Конструктор

Параметр	Тип	По умолчанию	Описание
`Экспортер`	`ОтелЭкспортерЛогов`	—	Экспортер записей логов

Методы

ПриПоявлении

Обрабатывает запись лога — синхронно передаёт экспортеру. После Закрыть() записи игнорируются. Ошибки экспортера логируются и не пробрасываются наверх.

Параметр	Тип	По умолчанию	Описание
`ЗаписьЛога`	`ОтелЗаписьЛога`	—	Запись лога
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Разрешённый контекст

Включен

Проверяет, будет ли процессор обрабатывать запись. Реализация не мутирует переданные объекты. Всегда возвращает Истина (процессор без фильтрации).

Параметр	Тип	По умолчанию	Описание
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Явный контекст
`ОбластьИнструментирования`	`ОтелОбластьИнструментирования`	`Неопределено`	Scope логгера
`СтепеньСерьезности`	`Число`	`0`	Номер серьезности
`ИмяСобытия`	`Строка`	`""`	Имя события

Возвращает: Булево

СброситьБуфер

Принудительно отправляет накопленные данные. Своего буфера у простого процессора нет: в пределах таймаута он дожидается экспорта, начатого в другом потоке, затем сбрасывает буфер экспортера.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (`0` — без ограничения)

Возвращает: ОтелРезультатЭкспорта — результат сброса буфера экспортера; таймаут, если экспорт в другом потоке не завершился за срок

Закрыть

Завершает работу процессора: дожидается текущего экспорта, сбрасывает буфер экспортера (СброситьБуфер) и закрывает экспортер — в пределах общего срока. Экспортер закрывается и после сбоя сброса буфера. После вызова ПриПоявлении игнорирует новые записи. Идемпотентен: повторный вызов возвращает успех.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЗакрытия — ошибка сброса буфера или закрытия экспортера; иначе таймаут, если истёк срок; иначе успех

ПринудительноВыгрузитьСРезультатом

Принудительно выгружает накопленные данные и возвращает результат.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут в миллисекундах

Возвращает: ОтелРезультатЗакрытия

Пример

bsl

Процессор = Новый ОтелПростойПроцессорЛогов(МойОтлпЭкспортер);

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Процессор)
    .Построить();

ОтелПроцессорСобытийВСобытияСпана

Процессор записей лога, переносящий события в события спана (EventToSpanEventBridge, спецификация Logs SDK, статус Development).

Описание

Событие в OpenTelemetry — запись лога с именем события (ОтелЗаписьЛога.УстановитьИмяСобытия). Семантические соглашения записывают исключения событиями: исключение операции — событием с именем вида db.client.operation.exception, исключение вне конкретной операции — событием exception. Процессор переносит такую запись в событие текущего спана, чтобы её было видно в представлениях, ориентированных на трассы, например в событиях спана в Grafana Tempo.

Запись переносится, только если выполнены все условия:

у записи непустое имя события;
у записи валидные идентификаторы трассировки и спана;
в разрешённом контексте записи есть текущий спан, который записывается (ЗаписьАктивна());
идентификаторы записи совпадают с идентификаторами этого спана.

Иначе процессор ничего не делает. Событие спана получает имя события записи, время записи (если оно не задано — время наблюдения) и все атрибуты записи, в том числе exception.*, которые логгер заполняет из УстановитьИсключение. Лимиты событий и их атрибутов — лимиты спана.

Запись после переноса продолжает путь по конвейеру: следующие процессоры, например процессор экспорта, получают её как обычно. Поэтому процессор ставят перед процессором экспорта. Если запись нужна только в спане, процессор экспорта логов не добавляют.

Автоконфигурация (ОтелАвтоконфигурация) ставит процессор первым, если ключ otel.oscript.event.to.span.event.bridge.enabled (OTEL_OSCRIPT_EVENT_TO_SPAN_EVENT_BRIDGE_ENABLED) равен true или не задан; другое значение процессор выключает. В файловой конфигурации процессор задают элементом event_to_span_event_bridge/development списка logger_provider.processors.

Реализует ИнтерфейсПроцессорЛогов. Настраиваемых параметров нет.

Конструктор

Без параметров.

Методы

ПриПоявлении

Переносит событие в событие текущего спана по условиям выше. После Закрыть() записи не переносятся. Ошибки переноса логируются в oscript.lib.opentelemetry.eventtospaneventbridge и не пробрасываются наверх.

Параметр	Тип	По умолчанию	Описание
`ЗаписьЛога`	`ОтелЗаписьЛога`	—	Запись лога
`Контекст`	`Соответствие`, `ФиксированноеСоответствие`, `Неопределено`	`Неопределено`	Разрешённый контекст; `Неопределено` — текущий контекст потока

Включен

Возвращает Истина, если в контексте есть записываемый текущий спан и процессор не закрыт: без спана процессору нечего делать. Пустое имя события означает, что оно не известно, и процессор не отключает. Реализация не мутирует переданные объекты.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`Соответствие`, `ФиксированноеСоответствие`, `Неопределено`	`Неопределено`	Явный контекст; `Неопределено` — текущий контекст потока
`ОбластьИнструментирования`	`ОтелОбластьИнструментирования`	`Неопределено`	Scope логгера
`СтепеньСерьезности`	`Число`	`0`	Номер серьезности
`ИмяСобытия`	`Строка`	`""`	Имя события

Возвращает: Булево

СброситьБуфер

Буфера у процессора нет.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (`0` — без ограничения)

Возвращает: ОтелРезультатЭкспорта — успех

Закрыть

Завершает работу процессора: следующие записи он не переносит.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (`0` — без ограничения)

Возвращает: ОтелРезультатЗакрытия — успех

Пример

Провайдер, собранный вручную: событие попадает в спан, а запись — в экспорт логов.

bsl

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Новый ОтелПроцессорСобытийВСобытияСпана())
    .ДобавитьПроцессор(ПакетныйПроцессор)
    .Построить();

Логгер = Провайдер.ПолучитьЛоггер("мой-сервис");
Спан = Трассировщик.НачатьСпан("ОформитьЗаказ");
Попытка
    ОформитьЗаказ();
Исключение
    Инфо = ИнформацияОбОшибке();
    Спан.УстановитьСтатус(ОтелКодСтатуса.Ошибка(), Инфо.Описание);
    Запись = Логгер.СоздатьЗаписьЛога()
        .УстановитьИмяСобытия("exception")
        .УстановитьСерьезность(ОтелСтепеньСерьезности.Error())
        .УстановитьИсключение(Инфо);
    Логгер.Записать(Запись, ОтелКонтекст.КонтекстСоСпаном(ОтелКонтекст.Текущий(), Спан));
КонецПопытки;
Спан.Завершить();

Файловая конфигурация:

yaml

logger_provider:
  processors:
    - event_to_span_event_bridge/development:
    - batch:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/logs

См. также

ОтелСтепеньСерьезности

Модуль констант степеней серьезности (SeverityNumber) по спецификации OpenTelemetry.

Описание

Значения соответствуют OTLP SeverityNumber enum. Используется для задания степени серьезности в ОтелЗаписьЛога.УстановитьСерьезность() и фильтрации в ОтелЛоггер.Включен().

Каждый уровень имеет диапазон из 4 значений (например, INFO = 9..12). Для стандартных уровней используйте именованные функции.

Методы

Trace

Возвращает номер серьезности TRACE (1).

Возвращает: Число — SEVERITY_NUMBER_TRACE

Debug

Возвращает номер серьезности DEBUG (5).

Возвращает: Число — SEVERITY_NUMBER_DEBUG

Info

Возвращает номер серьезности INFO (9).

Возвращает: Число — SEVERITY_NUMBER_INFO

Warn

Возвращает номер серьезности WARN (13).

Возвращает: Число — SEVERITY_NUMBER_WARN

Error

Возвращает номер серьезности ERROR (17).

Возвращает: Число — SEVERITY_NUMBER_ERROR

Fatal

Возвращает номер серьезности FATAL (21).

Возвращает: Число — SEVERITY_NUMBER_FATAL

ТекстСерьезности

Возвращает текстовое представление серьезности по номеру (TRACE, DEBUG, INFO, WARN, ERROR, FATAL). Номер 0 (SEVERITY_NUMBER_UNSPECIFIED) возвращает пустую строку.

Параметр	Тип	По умолчанию	Описание
`НомерСерьезности`	`Число`	—	Номер серьезности (SeverityNumber)

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

Пример

bsl

// Запись с уровнем INFO
Запись.УстановитьСерьезность(ОтелСтепеньСерьезности.Info());

// Запись с уровнем ERROR
Запись.УстановитьСерьезность(ОтелСтепеньСерьезности.Error());

// Фильтрация по уровню
Если Логгер.Включен(, , ОтелСтепеньСерьезности.Warn()) Тогда
    // создать и отправить запись
КонецЕсли;

// Получить текст по номеру
Текст = ОтелСтепеньСерьезности.ТекстСерьезности(17); // "ERROR"

ИнтерфейсПродюсерМетрик

Интерфейс продюсера метрик (MetricProducer) — внешнего источника готовых данных метрик.

Описание

Продюсер метрик подключает к читателю метрик источник уже агрегированных метрик, например мост к другой библиотеке метрик (спецификация Metrics SDK, раздел MetricProducer). При каждом сборе читатель вызывает функцию продюсера Произвести и добавляет полученные данные к метрикам своих метров: периодический читатель передаёт их экспортёру, Prometheus-читатель выдаёт вместе с остальными метриками.

Продюсер — объект с экспортной функцией Произвести(Ресурс, ТаймаутМс). Читатели вызывают её напрямую и не проверяют, что класс реализует интерфейс. Класс продюсера может отметить реализацию аннотацией &Реализует("ИнтерфейсПродюсерМетрик") библиотеки extends — так классы SDK отмечают свои интерфейсы. Создавать объект ИнтерфейсПродюсерМетрик не нужно.

Подключение к читателю

Продюсер регистрируют у читателя методом ДобавитьПродюсер: ОтелПериодическийЧитательМетрик или ОтелПрометеусЧитательМетрик. У провайдера метрик и его построителя такого метода нет; читатели провайдера, в том числе созданные автоконфигурацией, возвращает ЧитателиМетрик() ОтелПровайдерМетрик. Читатель вызывает продюсеры по очереди, в порядке добавления, при каждом своём сборе; продюсер, добавленный к нескольким читателям, вызывается при сборе каждого из них.

SDK не обрабатывает метрики продюсера: представления (Views), лимиты мощности, фильтры атрибутов и фильтр exemplars к ним не применяются.

Данные метрик

Метрики продюсер возвращает объектами ОтелДанныеМетрики (формат точек данных — на её странице):

ресурс — из параметра Ресурс: данные метрик содержат ресурс, поэтому читатель передаёт его продюсеру (спецификация, раздел Produce batch);
область инструментирования — одна на все метрики продюсера, она идентифицирует продюсер (спецификация, раздел Produce batch: Produce SHOULD include a single InstrumentationScope which identifies the MetricProducer);
временная агрегация — УстановитьВременнуюАгрегацию, если продюсер знает, как источник накапливает значения (спецификация, раздел MetricProducer: реализации SHOULD принимать настройку временной агрегации выдаваемых метрик). Без неё OTLP-экспортёр выбирает временную агрегацию своим селектором по типу метрики (ОтелСелекторВременнойАгрегации). Сумму и гистограмму с временной агрегацией Дельта() Prometheus-читатель пропускает с предупреждением в логе: Prometheus принимает только кумулятивные данные.

Метрике без ресурса читатель задаёт ресурс, переданный в Произвести, метрике без области — пустую область (без имени и версии): такие метрики экспортируются и выдаются, как остальные.

Продюсер может передавать и сводки (ОтелТипМетрики.Сводка), которых инструменты SDK не создают.

Ошибки и таймаут

Читатель вызывает Произвести в своём потоке сбора и не прерывает её: уложиться в ТаймаутМс должен сам продюсер. Если не успевает, он возвращает результат со статусом Timeout.

Сбой продюсера не мешает сбору: метрики метров и остальных продюсеров собираются как обычно, а о сбое сообщает результат сбора — ОтелРезультатЭкспорта из СброситьБуфер периодического читателя или выходной параметр РезультатСбора Prometheus-читателя:

исключение в Произвести или статус, отличный от Success и Timeout (обычно Failure), — результат сбора с ошибкой; в лог пишется предупреждение с описанием исключения или со статусом и СообщениеОшибки;
статус Timeout — результат сбора с таймаутом, если других сбоев нет; предупреждение в лог тоже пишется.

Метрики неуспешного результата читатель не использует, даже если они заполнены.

Периодический читатель вызывает продюсеры после сбора метров. Если срок сброса истёк, очередной продюсер и следующие за ним не вызываются: результат сбора сообщает о таймауте.

Прежний контракт: Произвести возвращала массив ОтелДанныеМетрики. Такой результат читатели по-прежнему принимают как успешный.

Методы

Произвести

Возвращает метрики источника. Реализует продюсер, вызывает читатель при каждом сборе.

Параметр	Тип	По умолчанию	Описание
`Ресурс`	`ОтелРесурс`	—	Ресурс провайдера метрик, у которого зарегистрирован читатель; у читателя без провайдера — ресурс по умолчанию (`ОтелРесурсы.ПоУмолчанию()`). Продюсер передаёт его в данные метрик
`ТаймаутМс`	`Число`	—	Время на производство в миллисекундах, `0` — без ограничения. Периодический читатель передаёт время, оставшееся до срока `СброситьБуфер`, `ПринудительноВыгрузитьСРезультатом` или `Закрыть`; при периодическом сборе и при вызове `СброситьБуфер()` самого читателя без срока — `0`. `СброситьБуфер()` и `Закрыть()` провайдера метрик без срока дают читателю срок 30000 мс. Prometheus-читатель всегда передаёт `0`: у сбора по запросу срока нет

Возвращает: ОтелРезультатПроизводстваМетрик — статус Success и метрики, Failure и сообщение об ошибке или Timeout, если продюсер не уложился в ТаймаутМс

Пример

Класс продюсера, файл МостМетрикОчереди.os:

bsl

Перем Область;
Перем ВремяЗапуска;

&Реализует("ИнтерфейсПродюсерМетрик")
Процедура ПриСозданииОбъекта()
    Область = Новый ОтелОбластьИнструментирования("queue-bridge", "1.0");
    ВремяЗапуска = ОтелУтилиты.ТекущееВремяВНаносекундах();
КонецПроцедуры

Функция Произвести(Ресурс, ТаймаутМс) Экспорт
    НачалоМс = ТекущаяУниверсальнаяДатаВМиллисекундах();
    Попытка
        Обработано = ПрочитатьСчетчикОчереди();
    Исключение
        Возврат Новый ОтелРезультатПроизводстваМетрик("Failure", , ОписаниеОшибки());
    КонецПопытки;
    Если ТаймаутМс > 0 И ТекущаяУниверсальнаяДатаВМиллисекундах() - НачалоМс > ТаймаутМс Тогда
        Возврат Новый ОтелРезультатПроизводстваМетрик("Timeout", , "Очередь не ответила в срок");
    КонецЕсли;

    Точка = Новый Соответствие();
    Точка.Вставить("attributes", Новый Массив());
    Точка.Вставить("startTimeUnixNano", ВремяЗапуска);
    Точка.Вставить("timeUnixNano", ОтелУтилиты.ТекущееВремяВНаносекундах());
    Точка.Вставить("value", Обработано);
    Точки = Новый Массив();
    Точки.Добавить(Точка);

    Данные = Новый ОтелДанныеМетрики(Ресурс, Область, "queue.messages.processed",
        "Обработанные сообщения", "{message}", ОтелТипМетрики.Сумма(), Точки, Истина);
    Данные.УстановитьВременнуюАгрегацию(ОтелВременнаяАгрегация.Кумулятивная());

    Метрики = Новый Массив();
    Метрики.Добавить(Данные);
    Возврат Новый ОтелРезультатПроизводстваМетрик("Success", Метрики);
КонецФункции

Функция ПрочитатьСчетчикОчереди()
    // ... запрос к брокеру очередей ...
    Возврат 42;
КонецФункции

Подключение к читателю:

bsl

ПодключитьСценарий("МостМетрикОчереди.os", "МостМетрикОчереди");

Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Читатель = Новый ОтелПериодическийЧитательМетрик(Новый ОтелЭкспортерМетрик(Транспорт));
Читатель.ДобавитьПродюсер(Новый МостМетрикОчереди());

Ресурс = ОтелРесурсы.ПоУмолчанию().ВПостроитель()
    .Установить("service.name", "queue-bridge")
    .Построить();

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьРесурс(Ресурс)
    .ЗарегистрироватьЧитатель(Читатель)
    .Построить();
Читатель.Запустить();

См. также

ОтелАгрегация

Модуль стратегий агрегации метрик.

Описание

ОтелАгрегация — глобальный модуль-фабрика конфигураций агрегации для инструментов метрик. Используется в ОтелПредставление и при настройке читателей.

Функции

ПоУмолчанию

Возвращает конфигурацию агрегации по умолчанию (Default): агрегацию выбирает SDK по виду инструмента — сумма для счётчиков и реверсивных счётчиков, последнее значение для датчиков, явная гистограмма для гистограмм. Читатель может задать для вида инструмента свою агрегацию по умолчанию, например экспоненциальную гистограмму для гистограмм (OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION).

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

Сумма

Возвращает конфигурацию суммирующей агрегации (Sum).

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

ПоследнееЗначение

Возвращает конфигурацию агрегации «последнее значение» (LastValue).

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

Отбросить

Возвращает конфигурацию агрегации «отбросить» (Drop) — данные не собираются.

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

ГистограммаСЯвнымиГраницами

Возвращает конфигурацию агрегации гистограммы с явно заданными границами бакетов (ExplicitBucketHistogram).

Границы задают по возрастанию. Неотсортированные границы SDK сортирует, повторы убирает и пишет в лог предупреждение. Пустой массив даёт гистограмму из одного бакета. Если в массиве есть элемент, который не является числом, представление (View) с такой агрегацией не применяется, в лог пишется предупреждение.

Параметр	Тип	По умолчанию	Описание
`Границы`	`Массив` из `Число`	`Неопределено`	Границы бакетов по возрастанию. `Неопределено` — границы по умолчанию: 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000
`ЗаписыватьМинМакс`	`Булево`	`Истина`	Записывать минимальное и максимальное значение (RecordMinMax). `Ложь` — в точке гистограммы нет `min` и `max`

Если ЗаписыватьМинМакс — не Булево, представление (View) с такой агрегацией не применяется, в лог пишется предупреждение.

Возвращает: Соответствие — Тип = "explicit_bucket_histogram", Границы, если они переданы, и ЗаписыватьМинМакс

ГистограммаЭкспоненциальная

Возвращает конфигурацию агрегации экспоненциальной гистограммы (Base2ExponentialBucketHistogram). Гистограмма начинает с максимальной шкалы; если бакетов не хватает, SDK понижает шкалу.

Параметр	Тип	По умолчанию	Описание
`МаксБакетов`	`Число`	`160`	Максимальное число бакетов положительных значений и отдельно — отрицательных (MaxSize); значение меньше 2 считается равным 2. Если значение не больше 0, представление (View) с такой агрегацией не применяется, в лог пишется предупреждение
`МаксШкала`	`Число`	`20`	Максимальная шкала (MaxScale) — целое число от -10 до 20
`ЗаписыватьМинМакс`	`Булево`	`Истина`	Записывать минимальное и максимальное значение (RecordMinMax). `Ложь` — в точке гистограммы нет `min` и `max`

Если МаксШкала вне диапазона от -10 до 20 или дробная, а ЗаписыватьМинМакс — не Булево, представление (View) с такой агрегацией не применяется, в лог пишется предупреждение.

Возвращает: Соответствие — Тип = "exponential_histogram", МаксБакетов, МаксШкала и ЗаписыватьМинМакс

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

Нормализовать — приводит конфигурацию агрегации (строку, Соответствие функций модуля, структуру или Неопределено — агрегацию по умолчанию) к структуре с полями Тип, Границы, МаксБакетов, МаксШкала, ЗаписыватьМинМакс; для неизвестной или некорректной конфигурации возвращает Неопределено;
РазрешитьПоУмолчанию — заменяет агрегацию по умолчанию агрегацией вида инструмента: последнее значение для Gauge и ObservableGauge, явная гистограмма для Histogram, сумма — для остальных видов;
СовместимаСВидом — проверяет, что агрегацию можно применить к виду инструмента: гистограммы несовместимы с асинхронными инструментами;
СоздатьАгрегаторПотока — создаёт агрегатор потока по агрегации и виду инструмента; у инструментов, записывающих отрицательные значения, сумма гистограммы не собирается;
ФабрикаРезервуаровПоУмолчанию — возвращает фабрику резервуаров exemplars по умолчанию для агрегации (см. Резервуар по умолчанию), для drop — Неопределено;
ЗаписываетОтрицательные — Истина для видов UpDownCounter, Gauge, ObservableUpDownCounter и ObservableGauge (другие модули SDK её не вызывают, её использует СоздатьАгрегаторПотока);
ЭтоАсинхронныйВид — Истина для видов ObservableCounter, ObservableUpDownCounter и ObservableGauge;
ЭтоАгрегаторОтбрасывания — проверяет, что агрегатор отбрасывает измерения (агрегация drop).

Пример

bsl

// Явные границы бакетов для гистограммы запросов
Границы = Новый Массив();
Границы.Добавить(0.005);
Границы.Добавить(0.01);
Границы.Добавить(0.025);
Границы.Добавить(0.05);
Границы.Добавить(0.1);
Границы.Добавить(0.25);
Границы.Добавить(0.5);
Границы.Добавить(1);

Агрегация = ОтелАгрегация.ГистограммаСЯвнымиГраницами(Границы);

Представление = Новый ОтелПредставление(
    Неопределено,    // НовоеИмя
    Неопределено,    // НовоеОписание
    Неопределено,    // РазрешенныеКлючиАтрибутов
    Неопределено,    // ГраницыГистограммы
    Агрегация);      // Агрегация

ОтелВременнаяАгрегация

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

Описание

ОтелВременнаяАгрегация — глобальный модуль с константами режимов временной агрегации метрик.

Тип временной агрегации определяет, как значения агрегируются во времени:

Кумулятивная — значения накапливаются с момента запуска: каждая точка содержит итог за всё время (у реверсивного счётчика итог может и уменьшаться)
Дельта — значения сбрасываются после каждой выгрузки; показывают изменение за период

Временную агрегацию для каждого вида инструмента выбирает селектор экспортёра — см. ОтелСелекторВременнойАгрегации.

Функции

НеУказана

Возвращает значение для неуказанного типа.

Возвращает: Число — 0

Кумулятивная

Возвращает значение для кумулятивной временной агрегации (Cumulative).

Агрегирование ведётся с момента запуска. После выгрузки данные не сбрасываются. Применяется для Prometheus-читателя.

Возвращает: Число — 2

Дельта

Возвращает значение для дельта-агрегации (Delta).

Агрегирование ведётся между выгрузками. После каждой выгрузки буфер сбрасывается.

Возвращает: Число — 1

Пример

bsl

// Сравнение типов временной агрегации
Если ВременнаяАгрегация = ОтелВременнаяАгрегация.Кумулятивная() Тогда
    Сообщить("Кумулятивный режим");
ИначеЕсли ВременнаяАгрегация = ОтелВременнаяАгрегация.Дельта() Тогда
    Сообщить("Дельта-режим");
КонецЕсли;

ОтелГистограмма

Гистограмма (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 с НовоеИмя меняет имя метрики в экспорте, а не имя инструмента.

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

Описание

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

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

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

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

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

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

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

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

Собрать — возвращает данные первого потока инструмента, не начиная новый интервал сбора;
ОчиститьТочкиДанных — завершает интервал сбора всех потоков: при дельта-временности начинает новый интервал, при кумулятивной сбрасывает exemplars;
КоличествоСерий — возвращает количество серий атрибутов первого потока;
УстановитьЛимитМощности — задаёт лимит мощности всех потоков (потокам метра его задают View, читатель или сам метр);
УстановитьФильтрЭкземпляров — задаёт фильтр exemplars всех потоков (потокам метра его задаёт провайдер);
УстановитьФабрикуРезервуаров — задаёт фабрику резервуаров exemplars всех потоков;
УстановитьРезервуарЭкземпляров — устаревший вариант: один резервуар exemplars на все серии потока, пишет предупреждение в лог;
УстановитьРазрешенныеКлючиАтрибутов, УстановитьИсключенныеКлючиАтрибутов — задают фильтр ключей атрибутов всех потоков (потокам метра его задаёт View).

Пример

bsl

ДлительностьЗапроса = Метр.СоздатьГистограмму(
    "http.request.duration", "Длительность HTTP-запроса", "s");

НачалоМс = ТекущаяУниверсальнаяДатаВМиллисекундах();
ОбработатьЗапрос();
ДлительностьСек = (ТекущаяУниверсальнаяДатаВМиллисекундах() - НачалоМс) / 1000;

Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("http.method", "POST");
Атрибуты.Установить("http.route", "/api/orders");
ДлительностьЗапроса.Записать(ДлительностьСек, Атрибуты);

// Дорогие атрибуты вычисляются, только если гистограмма включена.
// Включен вызывается перед каждой записью: результат может измениться
Если ДлительностьЗапроса.Включен() Тогда
    ДлительностьЗапроса.Записать(ДлительностьСек, ВычислитьАтрибутыЗапроса());
КонецЕсли;

ОтелДанныеМетрики

Данные одной метрики (MetricData): описание метрики и её точки данных.

Описание

ОтелДанныеМетрики передаёт данные метрики от источника к экспортёру. Экспортёр получает массив таких объектов в Экспортировать(МассивДанныхМетрик, Таймаут) (ОтелЭкспортерМетрик, свой экспортёр — ИнтерфейсЭкспортерМетрик), Prometheus-читатель переводит их в семейства Prometheus.

Данные создают:

SDK — при сборе потока метрики читателем: точки формирует агрегатор потока, временную агрегацию проставляет читатель;
продюсер метрик (ИнтерфейсПродюсерМетрик) — конструктором, из данных внешнего источника.

Объект хранит переданные значения как есть: конструктор их не проверяет и не копирует. Ресурс и область инструментирования обязательны: OTLP-экспортёр группирует по ним метрики в resourceMetrics и scopeMetrics, и с данными без них Экспортировать возвращает Ложь.

Конструктор

bsl

Новый ОтелДанныеМетрики(
    Ресурс,
    ОбластьИнструментирования,
    Имя,
    Описание,
    ЕдиницаИзмерения,
    ТипМетрики,
    ТочкиДанных,
    ФлагМонотонный,
    Тип
)

Параметр	Тип	По умолчанию	Описание
`Ресурс`	`ОтелРесурс`	—	Ресурс источника телеметрии. Продюсер передаёт ресурс, полученный в `Произвести`
`ОбластьИнструментирования`	`ОтелОбластьИнструментирования`	—	Область инструментирования: у данных SDK — область метра, у данных продюсера — область, которая идентифицирует продюсер
`Имя`	`Строка`	—	Имя метрики
`Описание`	`Строка`	—	Описание метрики
`ЕдиницаИзмерения`	`Строка`	—	Единица измерения, например `"s"` или `"By"`
`ТипМетрики`	`Строка`	—	Тип метрики из ОтелТипМетрики: `"sum"`, `"gauge"`, `"histogram"`, `"exponentialHistogram"` или `"summary"`. От него зависят ключи точек данных
`ТочкиДанных`	`Массив из Соответствие`	—	Точки данных, см. Точки данных
`ФлагМонотонный`	`Булево`	`Ложь`	Монотонность суммы: `Истина` — сумма только растёт (счётчик)
`Тип`	`Строка`	`"int"`	Тип значения точек суммы и датчика: `"int"` или `"double"`

У нового объекта временная агрегация не задана (Неопределено) и метаданных нет: их задают УстановитьВременнуюАгрегацию и УстановитьМетаданные.

Точки данных

Точка данных — Соответствие с ключами OTLP JSON. Время — строка с числом наносекунд от начала эпохи Unix, например "1700000000500000000"; текущее время возвращает ТекущееВремяВНаносекундах() модуля ОтелУтилиты.

Ключи точек всех типов:

Ключ	Тип	Описание
`attributes`	`Массив`	Атрибуты точки в формате OTLP: массив соответствий `{"key": ..., "value": {...}}`, как возвращает `ВМассивOtlp()` объекта ОтелАтрибуты; без атрибутов — пустой массив
`startTimeUnixNano`	`Строка`	Начало интервала, за который агрегированы значения. У датчика экспортёры его не используют
`timeUnixNano`	`Строка`	Время точки — конец интервала
`exemplars`	`Массив из Соответствие`	Необязательный: exemplars точки (см. ниже)

Сумма (sum) и датчик (gauge):

Ключ	Тип	Описание
`value`	`Число`	Сумма или последнее значение. OTLP-экспортёр передаёт его в `asDouble`, если тип значения `"double"` или число дробное, иначе в `asInt`

Гистограмма (histogram):

Ключ	Тип	Описание
`count`	`Число`	Количество измерений
`sum`	`Число`	Сумма измерений. Может отсутствовать: SDK не собирает её у инструментов, которые могут записывать отрицательные значения (реверсивный счётчик, датчик)
`min`, `max`	`Число`	Наименьшее и наибольшее измерение
`bucketCounts`	`Массив из Число`	Количество измерений в бакетах; бакетов на один больше, чем границ
`explicitBounds`	`Массив из Число`	Границы бакетов по возрастанию. В бакет с индексом `i` попадают значения больше границы `i - 1` и не больше границы `i`, в последний бакет — больше последней границы

Экспоненциальная гистограмма (exponentialHistogram):

Ключ	Тип	Описание
`count`	`Число`	Количество измерений
`sum`	`Число`	Сумма измерений; может отсутствовать, как у гистограммы
`min`, `max`	`Число`	Наименьшее и наибольшее измерение
`scale`	`Число`	Шкала бакетов
`zeroCount`	`Число`	Количество измерений в нулевом бакете
`zeroThreshold`	`Число`	Порог нулевого бакета; OTLP-экспортёр передаёт его, только если он больше 0
`positive`, `negative`	`Соответствие`	Бакеты положительных и отрицательных измерений: `offset` — индекс первого бакета, `bucketCounts` — массив количеств измерений

Сводка (summary) — её передают только продюсеры метрик:

Ключ	Тип	Описание
`count`	`Число`	Количество наблюдений
`sum`	`Число`	Сумма наблюдений
`quantileValues`	`Массив из Соответствие`	Квантили: `quantile` — уровень квантиля (например, `0.99`), `value` — значение

Exemplar — Соответствие в формате OTLP. Резервуары SDK заполняют ключи:

Ключ	Тип	Описание
`timeUnixNano`	`Строка`	Время измерения
`asDouble`	`Число`	Значение измерения
`traceId`, `spanId`	`Строка`	ID трассировки и спана в hex, если измерение синхронного инструмента записано в контексте валидного спана; у exemplars асинхронных инструментов этих ключей нет
`filteredAttributes`	`Массив`	Атрибуты измерения, которых нет в атрибутах точки (их отбросил фильтр атрибутов потока), в формате OTLP; если таких атрибутов нет, ключа нет

OTLP-экспортёр передаёт exemplars как есть (у сводки не передаёт), Prometheus-читатель выводит их в OpenMetrics у счётчиков и бакетов гистограмм.

Методы

Ресурс

Возвращает ресурс источника телеметрии.

Возвращает: ОтелРесурс

ОбластьИнструментирования

Возвращает область инструментирования.

Возвращает: ОтелОбластьИнструментирования

Имя

Возвращает имя метрики.

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

Описание

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

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

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

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

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

ТипМетрики

Возвращает тип метрики — значение ОтелТипМетрики. От него зависят ключи точек данных.

Возвращает: Строка — "sum", "gauge", "histogram", "exponentialHistogram" или "summary"

ТочкиДанных

Возвращает массив точек данных — тот же, что передан в конструктор: изменение массива или его точек меняет данные метрики.

Возвращает: Массив из Соответствие — см. Точки данных

Монотонный

Возвращает признак монотонности суммы. OTLP-экспортёр передаёт его в isMonotonic, Prometheus-читатель выводит монотонную сумму счётчиком (counter). SDK отмечает монотонными суммы инструментов, которые не записывают отрицательные значения, например счётчиков (синхронного и асинхронного).

Возвращает: Булево

ТипЗначения

Возвращает тип значения точек суммы и датчика. SDK задаёт "int" счётчикам и реверсивным счётчикам (синхронным и асинхронным), "double" — остальным инструментам.

Возвращает: Строка — "int" или "double"

ВременнаяАгрегация

Возвращает временную агрегацию, с которой собраны точки. Данным SDK её проставляет читатель: Кумулятивная() или Дельта() по виду инструмента (см. ОтелСелекторВременнойАгрегации). У данных продюсера она может быть не задана.

OTLP-экспортёр передаёт её в aggregationTemporality суммы, гистограммы и экспоненциальной гистограммы, а если она не задана — значение своего селектора для типа метрики. С ОтелВременнаяАгрегация.НеУказана() экспорт прерывается с предупреждением в логе. У датчика и сводки временной агрегации в OTLP нет.
Prometheus-читатель пропускает сумму и гистограмму с Дельта(), в лог пишется предупреждение.

Возвращает: Число, Неопределено — значение из ОтелВременнаяАгрегация; Неопределено — не задана

УстановитьВременнуюАгрегацию

Задаёт временную агрегацию точек. Продюсер метрик задаёт её, если знает, как источник накапливает значения.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`, `Неопределено`	—	Значение из ОтелВременнаяАгрегация; `Неопределено` — не задана

Метаданные

Возвращает метаданные метрики (metric.metadata в OTLP) — дополнительные сведения от источника данных. OTLP-экспортёр передаёт непустые метаданные в поле metadata. Prometheus-читатель берёт из ключа prometheus.type подсказку типа для датчика и немонотонной суммы: unknown, info или stateset (см. Подсказка типа датчика).

Возвращает: Соответствие — ключ → значение; пустое, если метаданных нет

УстановитьМетаданные

Задаёт метаданные метрики (metric.metadata).

Параметр	Тип	По умолчанию	Описание
`Значение`	`Соответствие`, `Неопределено`	—	Ключ → значение, значения — как у атрибутов (ОтелАтрибуты); `Неопределено` — метаданных нет

Пример

Данные метрики в продюсере метрик (Ресурс — параметр Произвести):

bsl

// Счетчик из внешнего источника: монотонная кумулятивная сумма
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("queue", "orders");

Точка = Новый Соответствие();
Точка.Вставить("attributes", Атрибуты.ВМассивOtlp());
Точка.Вставить("startTimeUnixNano", ВремяЗапуска); // строка, запомненная при запуске источника
Точка.Вставить("timeUnixNano", ОтелУтилиты.ТекущееВремяВНаносекундах());
Точка.Вставить("value", 42);
Точки = Новый Массив();
Точки.Добавить(Точка);

Область = Новый ОтелОбластьИнструментирования("queue-bridge", "1.0");
Данные = Новый ОтелДанныеМетрики(Ресурс, Область, "queue.messages.processed",
    "Обработанные сообщения", "{message}", ОтелТипМетрики.Сумма(), Точки, Истина);
Данные.УстановитьВременнуюАгрегацию(ОтелВременнаяАгрегация.Кумулятивная());

// Сводка (Summary): квантили считает источник
Квантиль = Новый Соответствие();
Квантиль.Вставить("quantile", 0.99);
Квантиль.Вставить("value", 0.9);
Квантили = Новый Массив();
Квантили.Добавить(Квантиль);

Точка = Новый Соответствие();
Точка.Вставить("attributes", Новый Массив());
Точка.Вставить("startTimeUnixNano", ВремяЗапуска);
Точка.Вставить("timeUnixNano", ОтелУтилиты.ТекущееВремяВНаносекундах());
Точка.Вставить("count", 12);
Точка.Вставить("sum", 5.5);
Точка.Вставить("quantileValues", Квантили);
Точки = Новый Массив();
Точки.Добавить(Точка);

Сводка = Новый ОтелДанныеМетрики(Ресурс, Область, "rpc.duration", "Длительность вызовов", "s",
    ОтелТипМетрики.Сводка(), Точки, Ложь, "double");

Чтение данных в своём экспортёре:

bsl

Функция Экспортировать(МассивДанныхМетрик, Таймаут = Неопределено) Экспорт
    Для Каждого Данные Из МассивДанныхМетрик Цикл
        Если Данные.ТипМетрики() <> ОтелТипМетрики.Сумма() Тогда
            Продолжить;
        КонецЕсли;
        Для Каждого Точка Из Данные.ТочкиДанных() Цикл
            Сообщить(СтрШаблон("%1 = %2", Данные.Имя(), Точка.Получить("value")));
        КонецЦикла;
    КонецЦикла;
    Возврат Истина;
КонецФункции

См. также

ОтелДатчик

Датчик (Gauge) — инструмент для записи мгновенного значения.

Описание

ОтелДатчик реализует спецификацию OpenTelemetry Gauge. Записывает текущее значение, перезаписывая предыдущее для данного набора атрибутов. Используется для абсолютных значений в данный момент (температура, загрузка CPU, использование памяти и т.д.). Все методы безопасны для конкурентного вызова из нескольких потоков.

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

Методы

Записать

Записывает текущее значение датчика.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Текущее значение
`Атрибуты`	`ОтелАтрибуты`	`Неопределено`	Атрибуты точки данных
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Явный контекст

Включен

Возвращает Ложь, если:

инструмент отключён закрытием провайдера: Закрыть() провайдера отключает инструменты его метров, в том числе созданные после закрытия;
инструмент создан no-op метром: его выдаёт закрытый провайдер и no-op провайдер, пока SDK не настроен;
все потоки инструмента используют агрегацию Drop (ОтелАгрегация.Отбросить()): её задаёт View или агрегация читателя по умолчанию для вида инструмента.

Иначе возвращает Истина.

Параметр	Тип	По умолчанию	Описание
`Атрибуты`	`ОтелАтрибуты`, `Неопределено`	`Неопределено`	Зарезервирован для будущих версий, на результат не влияет

Возвращает: Булево — Истина, если инструмент записывает измерения

Вид

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

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

Имя

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

Описание

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

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

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

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

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

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

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

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

Собрать — возвращает данные первого потока инструмента, не начиная новый интервал сбора;
ОчиститьТочкиДанных — завершает интервал сбора всех потоков: при дельта-временности начинает новый интервал, при кумулятивной сбрасывает exemplars;
КоличествоСерий — возвращает количество серий атрибутов первого потока;
УстановитьЛимитМощности — задаёт лимит мощности всех потоков (потокам метра его задают View, читатель или сам метр);
УстановитьФильтрЭкземпляров — задаёт фильтр exemplars всех потоков (потокам метра его задаёт провайдер);
УстановитьФабрикуРезервуаров — задаёт фабрику резервуаров exemplars всех потоков;
УстановитьРезервуарЭкземпляров — устаревший вариант: один резервуар exemplars на все серии потока, пишет предупреждение в лог;
УстановитьРазрешенныеКлючиАтрибутов, УстановитьИсключенныеКлючиАтрибутов — задают фильтр ключей атрибутов всех потоков (потокам метра его задаёт View).

Пример

bsl

ИспользованиеЦПУ = Метр.СоздатьДатчик(
    "system.cpu.utilization", "Загрузка CPU", "1");

// Записать текущее значение
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("cpu", "0");
ИспользованиеЦПУ.Записать(0.75, Атрибуты);

// Загрузка CPU измеряется, только если датчик включён.
// Включен вызывается перед каждой записью: результат может измениться
Если ИспользованиеЦПУ.Включен() Тогда
    ИспользованиеЦПУ.Записать(ИзмеритьЗагрузкуЦПУ(), Атрибуты);
КонецЕсли;

ОтелМетр

Метр (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 в спецификации не определён.

bsl

// Было (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-а доступно и по самому инструменту, и по его имени. Одноимённые инструменты разного вида или единицы различаются только по инструменту: по имени доступно наблюдение первого из них в списке. Инструмент, указанный в списке дважды, наблюдается один раз.

bsl

Процедура НаблюдатьЗадержку(Наблюдения, Датчики) Экспорт
    Наблюдения.Получить(Датчики.Миллисекунды).Записать(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-ам продолжается.

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

УстановитьМетрВключен — включает или выключает метр: провайдер выключает 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-ов через СобратьДляЧитателя.

Пример

bsl

Метр = Провайдер.ПолучитьМетр("мой-сервис", "1.0.0");

// Синхронные инструменты
Счетчик = Метр.СоздатьСчетчик("http.requests.total", "Всего HTTP-запросов", "{запросов}");
Гистограмма = Метр.СоздатьГистограмму("http.request.duration", "Длительность запроса", "s");
Датчик = Метр.СоздатьДатчик("system.memory.usage", "Использование памяти", "By");

// Наблюдаемый инструмент с callback
ОбратныйВызов = Новый Действие(ЭтотОбъект, "МойCallback");
НаблюдаемыйДатчик = Метр.СоздатьНаблюдаемыйДатчик(
    "queue.size", ОбратныйВызов, "Размер очереди", "{элементов}");

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

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

Описание

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

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

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

Методы

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

Вид

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

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

ДобавитьCallback

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

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

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

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

УдалитьCallback

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

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

Имя

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

Описание

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

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

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

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

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

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

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

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

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

Пример

bsl

// Наблюдать за текущей температурой
Процедура СобратьТемпературу(Наблюдение) Экспорт
    ЧипыЦПУ = ПолучитьСписокЧипов();
    Для Каждого Чип Из ЧипыЦПУ Цикл
        Атрибуты = Новый ОтелАтрибуты();
        Атрибуты.Установить("cpu", Чип.Номер);
        Наблюдение.Записать(Чип.Температура, Атрибуты);
    КонецЦикла;
КонецПроцедуры

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

ОтелНаблюдаемыйРеверсивныйСчетчик

Наблюдаемый реверсивный счётчик (ObservableUpDownCounter) — асинхронный инструмент, допускающий уменьшение значений.

Описание

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

Используется, когда нужно асинхронно наблюдать за значением, которое может расти и убывать (например, размер пула соединений, количество элементов в очереди).

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

Методы

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

Вид

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

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

ДобавитьCallback

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

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

УдалитьCallback

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

Имя

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

Описание

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

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

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

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

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

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

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

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

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

Пример

bsl

// Наблюдать за размером пула соединений
Процедура СобратьРазмерПула(Наблюдение) Экспорт
    Наблюдение.Записать(МойПулСоединений.Количество());
КонецПроцедуры

НаблюдаемыйРеверсивный = Метр.СоздатьНаблюдаемыйРеверсивныйСчетчик(
    "db.connections.pool.size",
    Новый Действие(ЭтотОбъект, "СобратьРазмерПула"),
    "Размер пула соединений",
    "{соединений}");

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

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

Описание

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

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

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

Методы

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

Вид

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

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

ДобавитьCallback

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

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

УдалитьCallback

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

Имя

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

Описание

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

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

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

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

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

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

СобратьДляЧитателя — вызывает 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
Регистрация.Закрыть();

ОтелНаблюдениеМетрики

Объект наблюдения метрики — передаётся в callback асинхронных инструментов.

Описание

ОтелНаблюдениеМетрики передаётся в callback асинхронных инструментов (ОтелНаблюдаемыйСчетчик, ОтелНаблюдаемыйРеверсивныйСчетчик, ОтелНаблюдаемыйДатчик).

В рамках одного вызова callback можно записать несколько значений с разными атрибутами.

Объект создаётся SDK автоматически — вручную не создаётся.

Методы

Записать

Записывает значение с опциональными атрибутами. Поддерживает fluent-цепочку.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Измеренное значение
`Атрибуты`	`ОтелАтрибуты`	`Неопределено`	Атрибуты точки данных

Возвращает: ОтелНаблюдениеМетрики — ЭтотОбъект (для fluent-цепочки)

Записи

Возвращает все записанные наблюдения.

Возвращает: Массив — массив структур {Значение: Число, Атрибуты: ОтелАтрибуты}

Количество

Возвращает количество записанных наблюдений.

Возвращает: Число

Пример

bsl

Процедура СобратьМетрики(Наблюдение) Экспорт
    // Запись одного значения
    Наблюдение.Записать(42);

    // Запись нескольких значений через fluent-цепочку
    Атрибуты1 = Новый ОтелАтрибуты();
    Атрибуты1.Установить("регион", "msk");

    Атрибуты2 = Новый ОтелАтрибуты();
    Атрибуты2.Установить("регион", "spb");

    Наблюдение
        .Записать(100, Атрибуты1)
        .Записать(85, Атрибуты2);

    // Проверить сколько наблюдений уже записано
    Сообщить("Записей: " + Наблюдение.Количество());
КонецПроцедуры

ОтелПериодическийЧитательМетрик

Периодический читатель метрик — собирает метрики по расписанию и отправляет их экспортёру.

Описание

ОтелПериодическийЧитательМетрик реализует 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"`, ...)

ВременнаяАгрегацияДляВида

Возвращает временную агрегацию потоков читателя для вида инструмента — её задаёт селектор экспортёра. Экспортёр без ПолучитьВременнуюАгрегацию получает кумулятивную.

Параметр	Тип	По умолчанию	Описание
`ВидИнструмента`	`Строка`	—	Вид инструмента

Возвращает: Число — значение из ОтелВременнаяАгрегация

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

ЗарегистрироватьУПровайдера — регистрирует читатель у провайдера при его создании и запоминает ресурс провайдера для продюсеров метрик. Читатель регистрируется только у одного провайдера: повторный вызов пишет ошибку в лог и возвращает Ложь, и провайдер такой читатель не добавляет.

Пример

bsl

Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерМетрик(Транспорт);
ПериодическийЧитатель = Новый ОтелПериодическийЧитательМетрик(Экспортер, 60000);

Построитель = Новый ОтелПостроительПровайдераМетрик();
Построитель.ЗарегистрироватьЧитатель(ПериодическийЧитатель);
Провайдер = Построитель.Построить();

// Запустить периодический сбор
ПериодическийЧитатель.Запустить();

// При завершении
ПериодическийЧитатель.Закрыть(5000);

ОтелПостроительМетра

Построитель метра (MeterBuilder): задаёт параметры области инструментирования и получает метр.

Описание

Создаётся через ПостроительМетра(ИмяБиблиотеки) провайдера метрик или ОтелSdk. Имя инструментирующей библиотеки задаётся при создании построителя, версия, адрес схемы и атрибуты области — методами построителя. Аналог Java SDK: MeterProvider.meterBuilder("name"). В спецификации OpenTelemetry построителя нет: это обёртка над получением метра (спецификация Metrics API, раздел Get a Meter).

Построить() получает метр так же, как ПолучитьМетр(ИмяБиблиотеки, ВерсияБиблиотеки, АтрибутыОбласти, АдресСхемы) провайдера: метр с той же областью — именем, версией, адресом схемы и атрибутами — возвращается из кэша провайдера, после закрытия провайдера возвращается no-op метр. Пустое имя библиотеки допускается: провайдер пишет предупреждение в лог и сохраняет имя в области как есть.

Незаданные параметры берутся по умолчанию: версия и адрес схемы — пустая строка, атрибутов области нет.

Методы

УстановитьВерсию

Задаёт версию инструментирующей библиотеки.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	Версия библиотеки

Возвращает: ОтелПостроительМетра — ЭтотОбъект для fluent API

УстановитьАдресСхемы

Задаёт адрес схемы телеметрии (schema URL) области.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	Адрес схемы, например `"https://opentelemetry.io/schemas/1.26.0"`

Возвращает: ОтелПостроительМетра — ЭтотОбъект для fluent API

УстановитьАтрибутыОбласти

Задаёт атрибуты области инструментирования (InstrumentationScope). Атрибуты входят в идентичность области: метры одной библиотеки с разными атрибутами — разные метры.

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелАтрибуты`	—	Атрибуты области

Возвращает: ОтелПостроительМетра — ЭтотОбъект для fluent API

Построить

Возвращает метр с заданными параметрами: из кэша провайдера, если метр с такой областью уже создан, иначе новый. Область хранит копию атрибутов: изменение объекта атрибутов после Построить() метр не меняет. После закрытия провайдера возвращает no-op метр.

Возвращает: ОтелМетр

Пример

bsl

АтрибутыОбласти = Новый ОтелАтрибуты();
АтрибутыОбласти.Установить("component", "http-client");

Метр = Провайдер.ПостроительМетра("my-library")
    .УстановитьВерсию("1.2.0")
    .УстановитьАдресСхемы("https://opentelemetry.io/schemas/1.26.0")
    .УстановитьАтрибутыОбласти(АтрибутыОбласти)
    .Построить();

Счетчик = Метр.СоздатьСчетчик("http.client.requests");

См. также

ОтелПостроительПровайдераМетрик

Построитель провайдера метрик (SdkMeterProviderBuilder) с fluent API.

Описание

Используется для пошаговой конфигурации ОтелПровайдерМетрик. Аналог Java SDK: SdkMeterProvider.builder().

Поддерживает настройку ресурса, нескольких читателей метрик, представлений (Views) и фильтра exemplars.

Значение OTEL_METRICS_EXEMPLAR_FILTER из окружения применяется автоматически при создании построителя.

Методы

УстановитьРесурс

Устанавливает ресурс, описывающий источник телеметрии.

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелРесурс`	—	Ресурс телеметрии

Возвращает: ОтелПостроительПровайдераМетрик — ЭтотОбъект для fluent API

ЗарегистрироватьЧитатель

Регистрирует читатель метрик (MetricReader). Аналог Java SDK: SdkMeterProviderBuilder.registerMetricReader(reader).

Параметр	Тип	По умолчанию	Описание
`Читатель`	`ОтелПериодическийЧитательМетрик`	—	Читатель метрик

Возвращает: ОтелПостроительПровайдераМетрик — ЭтотОбъект для fluent API

ЗарегистрироватьПредставление

Регистрирует представление (View) с селектором инструментов. Аналог Java SDK: SdkMeterProviderBuilder.registerView(selector, view).

Параметр	Тип	По умолчанию	Описание
`Селектор`	`ОтелСелекторИнструментов`	—	Селектор инструментов
`Представление`	`ОтелПредставление`	—	Представление

Возвращает: ОтелПостроительПровайдераМетрик — ЭтотОбъект для fluent API

УстановитьФильтрЭкземпляров

Устанавливает фильтр exemplars (ExemplarFilter). Аналог Java SDK: SdkMeterProviderBuilder.setExemplarFilter(filter).

Параметр	Тип	По умолчанию	Описание
`Фильтр`	`Число`	—	Фильтр из `ОтелФильтрЭкземпляров`

Возвращает: ОтелПостроительПровайдераМетрик — ЭтотОбъект для fluent API

Построить

Создаёт экземпляр провайдера метрик с заданными параметрами.

Возвращает: ОтелПровайдерМетрик

Пример

bsl

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьРесурс(Ресурс)
    .ЗарегистрироватьЧитатель(
        Новый ОтелПериодическийЧитательМетрик(Экспортер)
    )
    .ЗарегистрироватьПредставление(
        Новый ОтелСелекторИнструментов("запросы"),
        Новый ОтелПредставление(, , МассивКлючейАтрибутов)
    )
    .Построить();

ОтелПредставление

Представление (View) — конфигурация агрегации и фильтрации для инструмента метрик.

Описание

ОтелПредставление позволяет переопределить имя, описание, атрибуты, границы гистограммы и тип агрегации для отдельных инструментов метрик — синхронных и асинхронных.

Регистрируется вместе с селектором инструментов методом ЗарегистрироватьПредставление(Селектор, Представление)ОтелПостроительПровайдераМетрик или ОтелПровайдерМетрик: селектор задаёт, к каким инструментам применяется View.

Правила применения:

каждый View, выбравший инструмент, даёт отдельный поток метрики у каждого читателя;
настройки View приоритетнее advisory-параметров инструмента: ГраницыГистограммы View приоритетнее advisory-границ, а агрегация explicit_bucket_histogram из View advisory-границы не использует; без РазрешенныеКлючиАтрибутов и ИсключенныеКлючиАтрибутов поток сохраняет все атрибуты;
аспекты, которые View не задал, берутся у читателя: агрегация и лимит мощности по умолчанию для вида инструмента;
View с семантической ошибкой (агрегация, несовместимая с видом инструмента, например гистограмма для асинхронного инструмента, или неизвестная агрегация) игнорируется целиком — как если бы его не было, в лог пишется предупреждение;
если View даёт двум потокам одного читателя одно имя (например, переименовывает инструмент в имя существующего), оба потока экспортируются, в лог пишется предупреждение о конфликте идентичности метрик;
View, зарегистрированный после создания инструмента, применяется к измерениям, записанным после регистрации.

Exemplars и отфильтрованные атрибуты. Атрибуты, исключённые представлением (РазрешенныеКлючиАтрибутов, ИсключенныеКлючиАтрибутов), всё равно могут экспортироваться в exemplars как filteredAttributes. Чтобы они не уходили в exemplars, выключите exemplars фильтром ОтелФильтрЭкземпляров.ВсегдаВыключен() (ОтелФильтрЭкземпляров, OTEL_METRICS_EXEMPLAR_FILTER=always_off) или передайте Новый ОтелФабрикаNoopРезервуаров() (ОтелФабрикаNoopРезервуаров) в параметр РезервуарЭкземпляров.

Конструктор

Все параметры опциональны.

Параметр	Тип	По умолчанию	Описание
`НовоеИмя`	`Строка`	`Неопределено`	Переопределённое имя инструмента
`НовоеОписание`	`Строка`	`Неопределено`	Переопределённое описание
`РазрешенныеКлючиАтрибутов`	`Массив`	`Неопределено`	Список разрешённых ключей атрибутов (см. Ключи атрибутов)
`ГраницыГистограммы`	`Массив`	`Неопределено`	Явные границы бакетов гистограммы
`Агрегация`	`ОтелАгрегация`	`Неопределено`	Стратегия агрегации
`ИсключенныеКлючиАтрибутов`	`Массив`	`Неопределено`	Список исключённых ключей атрибутов (см. Ключи атрибутов)
`РезервуарЭкземпляров`	Фабрика резервуаров	`Неопределено`	Фабрика резервуаров exemplars потока — объект с методом `СоздатьРезервуар()`: резервуар создаётся на каждую серию. Готовые фабрики: ОтелФабрикаПростыхРезервуаров, ОтелФабрикаВыровненныхРезервуаровГистограммы, ОтелФабрикаNoopРезервуаров (отключает exemplars); свой резервуар — см. ОтелРезервуарЭкземпляров. Объект без `СоздатьРезервуар()` отклоняется с ошибкой в логе, используется резервуар по умолчанию
`ЛимитМощностиАгрегации`	`Число`	`Неопределено`	Лимит cardinality

Ключи атрибутов

Ключ в списках РазрешенныеКлючиАтрибутов и ИсключенныеКлючиАтрибутов — точное значение или шаблон: ? — любой один символ, * — любое число любых символов, в том числе ни одного. Ключи сравниваются с учётом регистра, остальные символы шаблона, включая точку, — как есть. Например, http.* оставляет http.method и http.route, но не HTTP.method. Если ключ атрибута совпал с обоими списками, атрибут отбрасывается.

Методы

НовоеИмя

Возвращает: Строка, Неопределено

НовоеОписание

Возвращает: Строка, Неопределено

РазрешенныеКлючиАтрибутов

Возвращает: Массив, Неопределено

ИсключенныеКлючиАтрибутов

Возвращает: Массив, Неопределено

ГраницыГистограммы

Возвращает: Массив, Неопределено

Агрегация

Возвращает: ОтелАгрегация, Неопределено

РезервуарЭкземпляров

Возвращает: фабрика резервуаров или Неопределено

ЛимитМощностиАгрегации

Возвращает: Число, Неопределено

Пример

bsl

// Переименовать инструмент и задать границы гистограммы
Границы = Новый Массив();
Границы.Добавить(0.005);
Границы.Добавить(0.01);
Границы.Добавить(0.025);
Границы.Добавить(0.05);
Границы.Добавить(0.1);
Границы.Добавить(0.25);
Границы.Добавить(0.5);
Границы.Добавить(1);

Представление = Новый ОтелПредставление(
    "http_request_duration_seconds",    // НовоеИмя
    Неопределено,                       // НовоеОписание
    Неопределено,                       // РазрешенныеКлючиАтрибутов
    Границы);                           // ГраницыГистограммы

Селектор = Новый ОтелСелекторИнструментов("http.request.duration");
Построитель = Новый ОтелПостроительПровайдераМетрик();
Построитель.ЗарегистрироватьПредставление(Селектор, Представление);

См. также

ОтелПровайдерМетрик

Провайдер метрик (MeterProvider) — центральная точка управления метрами и читателями метрик.

Описание

ОтелПровайдерМетрик реализует спецификацию OpenTelemetry MeterProvider. Хранит кэш объектов ОтелМетр по идентичности области (имя библиотеки, версия, адрес схемы и атрибуты scope), управляет представлениями (Views) и читателями метрик. Поддерживает несколько читателей.

У каждого читателя свои потоки метрик: агрегацию и лимит мощности по умолчанию для вида инструмента, а также временную агрегацию задаёт читатель, поэтому сбор одним читателем не сбрасывает и не искажает данные другого. Каждый совпавший с инструментом View даёт отдельный поток. Изменения конфигурации (Views, агрегация гистограмм по умолчанию) применяются и к ранее выданным метрам.

Все публичные методы потокобезопасны.

Рекомендуется создавать через ОтелПостроительПровайдераМетрик.

Методы

ПостроительМетра

Создаёт построитель метра (MeterBuilder). Аналог Java SDK: MeterProvider.meterBuilder("name").

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки

Возвращает: ОтелПостроительМетра

ПолучитьМетр

Создаёт или возвращает из кэша метр для указанной библиотеки. После Закрыть() и у no-op провайдера, который действует, пока SDK не настроен, возвращает no-op метр: он не проверяет параметры и не пишет в лог, его инструменты выключены и не хранят измерений.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки
`АтрибутыОбласти`	`ОтелАтрибуты`	`Неопределено`	Атрибуты InstrumentationScope
`АдресСхемы`	`Строка`	`""`	URL схемы телеметрии

Возвращает: ОтелМетр

Ресурс

Возвращает ресурс провайдера.

Возвращает: ОтелРесурс

ЧитательМетрик

Возвращает первый зарегистрированный читатель метрик (для обратной совместимости).

Возвращает: ОтелПериодическийЧитательМетрик, Неопределено

ЧитателиМетрик

Возвращает массив всех зарегистрированных читателей метрик.

Возвращает: Массив

ФильтрЭкземпляров

Возвращает фильтр exemplars провайдера.

Возвращает: Число — константа ОтелФильтрЭкземпляров: ВсегдаВключен(), ВсегдаВыключен() или ПоТрассировке()

СброситьБуфер

Принудительно экспортирует все накопленные метрики через все читатели. У каждого читателя вызывается его собственный ForceFlush — ПринудительноВыгрузитьСРезультатом (сбор, экспорт и сброс буфера экспортера), а у читателя без этого метода (например, pull-читателя) — СброситьБуфер. Сброс вызывается у каждого читателя, даже если предыдущий бросил исключение; все читатели укладываются в общий срок — каждому передаётся оставшееся время.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЭкспорта — ошибка, если хотя бы один читатель сообщил о сбое или бросил исключение; иначе таймаут, если истёк срок или читатель сообщил о таймауте; иначе успех

Закрыть

Завершает работу провайдера: отключает синхронные инструменты метров, в том числе те, что метры создадут после закрытия (наблюдаемые инструменты и мульти-callback-и, созданные после закрытия, — no-op и не хранят callback-и), и закрывает читателей в пределах общего срока — каждого, даже после исключения в предыдущем и после истечения срока (тогда читатель получает 1 мс и завершается без ожидания). Идемпотентен: повторный вызов возвращает успех. После закрытия ПолучитьМетр() возвращает no-op метр.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут операции в миллисекундах (0 — без ограничения; читателям передаётся по 30000)

Возвращает: ОтелРезультатЗакрытия — ошибка, если хотя бы один читатель вернул ошибку или бросил исключение (описания ошибок перечислены через ; ); иначе таймаут, если истёк срок или читатель сообщил о таймауте; иначе успех

ПринудительноВыгрузитьСРезультатом

Принудительно выгружает все накопленные метрики через читателей так же, как СброситьБуфер. После Закрыть() возвращает ошибку.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут операции в миллисекундах

Возвращает: ОтелРезультатЗакрытия

СброситьБуферАсинхронно

Асинхронно сбрасывает буфер.

Возвращает: Обещание

ЗакрытьАсинхронно

Асинхронно завершает работу провайдера.

Возвращает: Обещание

ЗарегистрироватьПредставление

Регистрирует представление (View) с селектором инструментов. View применяется и к инструментам ранее выданных метров: их потоки разрешаются заново, измерения после регистрации попадают в потоки с новой конфигурацией. Потоки, конфигурация которых не изменилась, сохраняют накопленные данные.

Параметр	Тип	По умолчанию	Описание
`Селектор`	`ОтелСелекторИнструментов`	—	Селектор инструментов
`Представление`	`ОтелПредставление`	—	Представление

ПолучитьПредставления

Возвращает зарегистрированные представления.

Возвращает: Массив из Соответствие — пары с ключами Селектор и Представление

УстановитьАгрегациюГистограммПоУмолчанию

Устанавливает агрегацию гистограмм по умолчанию для метров провайдера без читателей (у читателей своя агрегация по умолчанию для вида инструмента). Применяется и к ранее выданным метрам. Соответствует OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	`explicit_bucket_histogram` или `base2_exponential_bucket_histogram`

УстановитьТаймаутОбратныхВызововМс

Задаёт таймаут callback-ов асинхронных инструментов и мульти-callback-ов метров провайдера (по умолчанию 30000 мс). Применяется и к ранее выданным метрам. См. ОтелМетр.УстановитьТаймаутОбратныхВызововМс.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Таймаут в миллисекундах; 0 — callback-и выполняются в потоке сбора без таймаута

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

УстановитьВключен — выключает провайдер: им выключены no-op провайдер, который ОтелГлобальный возвращает, пока SDK не настроен, и провайдер SDK с disabled: true в файле конфигурации. Выключенный провайдер выдаёт no-op метры;
Включен — Ложь у выключенного провайдера. Закрытие признак не меняет.

Пример

bsl

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьРесурс(Ресурс)
    .ЗарегистрироватьЧитатель(Читатель)
    .Построить();

Метр = Провайдер.ПолучитьМетр("мой-сервис", "1.0.0");
Счетчик = Метр.СоздатьСчетчик("запросы");
Счетчик.Добавить(1);

// Завершение работы
Провайдер.Закрыть();

ОтелПрометеусЧитательМетрик

Prometheus-читатель метрик — переводит метрики OTel в Prometheus text format.

Описание

ОтелПрометеусЧитательМетрик реализует pull-модель сбора метрик для Prometheus. Метрики собираются по запросу и переводятся в семейства Prometheus, а текст в формате Prometheus text exposition 0.0.4 формирует библиотека prometheus — зависимость пакета.

Всегда использует кумулятивную временную агрегацию (Cumulative).

Формат выдачи

СобратьВТексте выдаёт text format 0.0.4 (text/plain; version=0.0.4; charset=utf-8), имена экранируются по схеме underscores. Строк # UNIT, времени создания серий _created и exemplars в text format нет. Семейства читателя содержат их для OpenMetrics: если читатель зарегистрирован в реестре библиотеки prometheus (см. Collect), формат выдачи реестра выбирает библиотека.

Имена метрик

Перевод имён OTel в имена Prometheus выполняется только в этом читателе: имена и единицы инструментов, а также OTLP-экспорт не меняются. По спецификации Prometheus and OpenMetrics Compatibility (стратегия UnderscoreEscapingWithSuffixes, других стратегий трансляции нет):

недопустимые символы имени заменяются на _: http.server.requests → http_server_requests;
единица UCUM переводится в слово Prometheus и добавляется суффиксом перед суффиксом типа: s → _seconds, By → _bytes, % → _percent (полная таблица — в спецификации);
части единицы в фигурных скобках отбрасываются ({request} суффикса не даёт), скорость X/Y становится X_per_Y (By/s → _bytes_per_second), безразмерная 1 суффикса не даёт;
суффикс не добавляется, если имя уже оканчивается на эту единицу;
к монотонной сумме (Counter) добавляется _total, если имя им ещё не оканчивается; имя, которое уже оканчивается на _total, не меняется (requests_total_total так и выводится). Строки # HELP и # TYPE счётчика в text format относятся к имени сэмпла (# TYPE http_requests_total counter), в OpenMetrics — к имени без _total (# TYPE http_requests counter).

Инструмент OTel	Имя сэмпла Prometheus
Гистограмма `http.server.request.duration`, `s`	`http_server_request_duration_seconds_bucket` / `_sum` / `_count`
Счётчик `net.io`, `By`	`net_io_bytes_total`
Счётчик `http.requests`, `{request}`	`http_requests_total`
Датчик `cpu.utilization`, `1`	`cpu_utilization`

Одноимённые метрики одного типа объединяются в одно семейство. Метрика другого типа пропускается целиком, в том числе когда совпадает только имя в строке # TYPE text format: счётчик foo с единицей By (# TYPE foo_bytes_total counter) и датчик foo_bytes_total, info-метрика x и датчик x_info. Точка отбрасывается, если сэмпл с тем же именем и набором лейблов уже есть в выдаче, в том числе в другом семействе. Например, так бывает у метрик a.b и a_b одной области, у счётчика foo с единицей By (сэмпл foo_bytes_total) и датчика foo_bytes_total или у счётчика foo (сэмпл foo_created в OpenMetrics) и датчика foo_created. В обоих случаях в лог пишется предупреждение.

Лейблы атрибутов

Атрибуты точек становятся лейблами (спецификация, раздел Metric Attributes):

в имени лейбла символы вне [a-zA-Z0-9_], включая :, заменяются на _: http:method → http_method;
строковое значение выводится как есть, двоичные данные — в base64, пустое значение (Неопределено) — пустой строкой, остальные — в JSON: true/false, 2.5, ["x","y"], отображение — JSON-объектом {"nested":true} (спецификация, раздел Common / AnyValue representation for non-OTLP protocols);
если ключи совпали после замены символов (a.b и a_b), значения склеиваются через ; в порядке исходных ключей: a_b="first;second". Так же склеиваются атрибут точки и лейбл области (otel.scope.name и otel_scope_name: otel_scope_name="user;lib") или скопированный атрибут ресурса; при равных ключах первым идёт значение атрибута точки.

Лейблы области

На каждый сэмпл добавляются лейблы области инструментирования (спецификация, раздел Instrumentation Scope):

Лейбл	Значение
`otel_scope_name`	имя области
`otel_scope_version`	версия области
`otel_scope_schema_url`	адрес схемы области
`otel_scope_<атрибут>`	атрибуты области, имя лейбла нормализуется как у атрибутов точек

Пустые имя, версия и адрес схемы лейбла не дают. Атрибут области, который после префикса совпадает с otel_scope_name, otel_scope_version или otel_scope_schema_url, отбрасывается. Поэтому серии метров с одинаковыми именем и версией, но разными адресами схемы или атрибутами не склеиваются.

Атрибуты ресурса

Ресурс отдельной метрикой (target_info) не выводится: этот раздел спецификации (Resource Attributes) в статусе Development. По умолчанию атрибуты ресурса в лейблы метрик не копируются; УстановитьАтрибутыРесурсаВЛейблах копирует выбранные атрибуты.

Подсказка типа датчика

Датчик и немонотонная сумма выводятся по подсказке prometheus.type из метаданных метрики (ОтелДанныеМетрики.Метаданные(), спецификация, раздел Gauges). Метаданные задаёт источник данных, например производитель метрик, переносящий метрики Prometheus. Типы unknown, info и stateset есть только в OpenMetrics, в text format они выводятся так, как предписывает спецификация для форматов без этих типов:

`prometheus.type`	Text format	OpenMetrics
нет, `gauge`, другое значение	`gauge`	`gauge`
`unknown` (и `unkown`)	`untyped`	`unknown`
`info`	`gauge <имя>_info`, значение `1`	`info <имя>`, сэмпл `<имя>_info`, значение `1`
`stateset`	`gauge`	`stateset`

Единица и время создания серий

В OpenMetrics слово единицы, добавленное к имени, выводится строкой # UNIT (спецификация, раздел Metric Metadata), кроме info и stateset. У семейства одна строка # UNIT — первой метрики; отличающаяся единица одноимённой метрики отбрасывается с предупреждением, точки метрики остаются.

Время старта точки выводится временем создания серии <имя>_created (секунды): у счётчика после значения, у гистограммы и сводки после _count. У датчика времени создания нет.

# TYPE http_duration_seconds histogram
# UNIT http_duration_seconds seconds
http_duration_seconds_bucket{le="0.005"} 0
...
http_duration_seconds_sum 0.2
http_duration_seconds_count 1
http_duration_seconds_created 1700000000.5

Гистограммы

Гистограмма выводится Prometheus histogram (спецификация, раздел Histograms as Prometheus Histograms): бакеты _bucket по возрастанию границы le с накопленным количеством, последний — +Inf, затем _sum и _count. Если у точки нет суммы, _sum не выводится. Так бывает у реверсивного счётчика и датчика с View гистограммы — SDK не собирает сумму, если инструмент записывает отрицательные значения, — и у точки продюсера метрик: в OTLP сумма гистограммы необязательна.

# TYPE queue histogram
queue_bucket{le="0"} 1
queue_bucket{le="10"} 2
queue_bucket{le="+Inf"} 2
queue_count 2

Сводки (Summary)

Сводка (ОтелТипМетрики.Сводка, обычно от продюсера метрик) выводится Prometheus summary (спецификация, раздел Summaries): квантили — сэмплами с лейблом quantile по возрастанию квантиля, затем _sum и _count. Exemplars сводки не выводятся.

# TYPE rpc_duration_seconds summary
rpc_duration_seconds{quantile="0.5"} 0.2
rpc_duration_seconds{quantile="0.99"} 0.9
rpc_duration_seconds_sum 5.5
rpc_duration_seconds_count 12

Exemplars

Exemplars выводятся только в OpenMetrics (спецификация, разделы Sums, Histograms и Exemplar Conversion); в text format их нет:

у счётчика — последний exemplar точки, у каждого бакета гистограммы — последний из попавших в бакет (граница бакета — верхняя, значение на границе попадает в этот бакет);
ID трассировки и спана выводятся лейблами trace_id и span_id, они приоритетнее одноимённых атрибутов; время exemplar выводится в секундах;
отфильтрованные атрибуты (filteredAttributes) выводятся лейблами, если вместе с trace_id и span_id не превышают лимит OpenMetrics 1.0 — 128 символов в именах и значениях лейблов; иначе exemplar выводится без них;
exemplars датчика, немонотонной суммы и сводки не выводятся.

# TYPE jobs counter
jobs_total 5 # {span_id="b7ad6b7169203331",trace_id="0af7651916cd43dd8448eb211c80319c"} 0.7 1700000003
jobs_created 1700000000.5
# EOF

Отброшенные данные

О любой отброшенной метрике, точке или метаданных в лог пишется предупреждение: конфликт TYPE, повторный сэмпл, экспоненциальная гистограмма (text format и OpenMetrics её не поддерживают), сумма или гистограмма с временной агрегацией Дельта, ошибка перевода метрики, описание или единица метрики, отличные от # HELP или # UNIT семейства, в которое она добавлена.

Отдача по HTTP

HTTP-сервера в читателе нет: метрики отдаёт приложение. Из своего HTTP-обработчика /metrics (например, контроллера Winow) верните СобратьВТексте с заголовком Content-Type из ContentType. Либо зарегистрируйте читатель в реестре библиотеки prometheus (Collect) и отдавайте реестр, например, через prometheus-metrics.

Конструктор

Без параметров. Создаётся через ОтелПостроительПровайдераМетрик.

Методы

ДобавитьМетр

Регистрирует метр в читателе.

Параметр	Тип	По умолчанию	Описание
`Метр`	`ОтелМетр`	—	Метр для регистрации

ДобавитьПродюсер

Регистрирует продюсер внешних метрик (MetricProducer): его метрики, например сводки (Summary) из мостов к другим библиотекам, выдаются вместе с метриками метров. Читатель вызывает Произвести(Ресурс, ТаймаутМс) с ресурсом провайдера, у которого зарегистрирован (без провайдера — с ресурсом по умолчанию), и таймаутом 0: сбор по запросу срока не имеет. Сумма или гистограмма продюсера с временной агрегацией Дельта пропускается с предупреждением: Prometheus принимает только кумулятивные данные. Сбой продюсера (исключение или статус ошибки) логируется, делает результат сбора ошибкой и не лишает выдачу остальных метрик.

Параметр	Тип	По умолчанию	Описание
`Продюсер`	`ИнтерфейсПродюсерМетрик`	—	Продюсер метрик

СобратьВТексте

Собирает все метрики и возвращает их в text format 0.0.4 (см. Формат выдачи): семейства СобратьСемейства, сериализованные библиотекой prometheus (Prometheus.СериализоватьВТекст). Сбой сбора одного метра или инструмента логируется и не лишает выдачу метрик остальных; о сбое сообщает РезультатСбора. Если метрик нет или читатель закрыт, возвращает пустую строку. Одновременные запросы собирают метрики по очереди: callback-и инструментов одного сбора завершаются до начала следующего.

Параметр	Тип	По умолчанию	Описание
`РезультатСбора`	`ОтелРезультатЭкспорта`	`Неопределено`	Выходной параметр: ошибка, если сбор метра, инструмента, callback-а или продюсера завершился сбоем (их метрики не попадают в выдачу) или читатель закрыт; таймаут, если callback или продюсер не уложился в таймаут; иначе успех

Возвращает: Строка — метрики в text format 0.0.4

ContentType

Возвращает значение заголовка Content-Type ответа СобратьВТексте.

Возвращает: Строка — "text/plain; version=0.0.4; charset=utf-8"

ПолучитьВременнуюАгрегацию

Возвращает тип временной агрегации для инструмента.

Всегда возвращает Кумулятивная независимо от типа инструмента.

Параметр	Тип	По умолчанию	Описание
`ТипИнструмента`	`Строка`	—	Тип инструмента

Возвращает: ОтелВременнаяАгрегация.Кумулятивная()

СобратьСемейства

Собирает все метрики как семейства в промежуточном формате библиотеки prometheus: Соответствие с ключами Имя, Тип, Справка, Единица, Сэмплы.

Тип — вид метрики Prometheus: counter, gauge, histogram, summary, unknown, info или stateset; в text format библиотека выводит unknown как untyped, info и stateset — как gauge.
Единица — слово единицы для строки # UNIT в OpenMetrics.
У сэмпла — ИмяСэмпла, Лейблы, Значение; у квантиля сводки ещё Квантиль (уровень квантиля: по нему библиотека упорядочивает квантили серии).
У сэмпла счётчика и бакета гистограммы — Экземпляр (exemplar: Лейблы, Значение, Время в секундах), у сэмпла счётчика и _count гистограммы и сводки — Создано (время старта точки в секундах).

Имя — имя метрики в строках # HELP и # TYPE text format. У счётчика оно совпадает с именем сэмпла (http_requests_total при стратегии с суффиксами), у info-метрики — с суффиксом _info, у гистограммы это имя без _bucket, _sum и _count. Для OpenMetrics библиотека отрезает суффиксы _total и _info. Результат можно передать в Prometheus.СериализоватьВТекст: в text format 0.0.4 текст будет тот же, что у СобратьВТексте. После Закрыть возвращает пустой массив.

Параметр	Тип	По умолчанию	Описание
`РезультатСбора`	`ОтелРезультатЭкспорта`	`Неопределено`	Выходной параметр: ошибка, если сбор метра, инструмента, callback-а или продюсера завершился сбоем (их метрики не попадают в выдачу) или читатель закрыт; таймаут, если callback или продюсер не уложился в таймаут; иначе успех

Возвращает: Массив — массив семейств метрик Prometheus

Collect

Возвращает семейства метрик (СобратьСемейства) для реестра библиотеки prometheus: читатель регистрируется в CollectorRegistry как custom Collector и выдаётся вместе с метриками библиотеки. Формат выдачи реестра (text format или OpenMetrics) выбирает библиотека. Чтобы обращаться к реестру из своего кода, подключите библиотеку (#Использовать prometheus).

bsl

Реестр = Prometheus.РеестрПоУмолчанию();
Реестр.Register(ПрометеусЧитатель);
Текст = Prometheus.СериализоватьВТекст(Prometheus.СобратьМетрики(Реестр));

Возвращает: Массив — массив семейств метрик Prometheus

УстановитьАтрибутыРесурсаВЛейблах

Включает копирование атрибутов ресурса в лейблы метрик (resource_constant_labels). По умолчанию атрибуты ресурса не копируются. Значения атрибута точки и атрибута ресурса с тем же именем лейбла склеиваются через ; в порядке исходных ключей, при равных ключах первым идёт значение точки.

Параметр	Тип	По умолчанию	Описание
`Включаемые`	`Массив`, `Неопределено`	—	Шаблоны ключей включаемых атрибутов: `*` — любые символы, `?` — один символ; `Неопределено` — все атрибуты
`Исключаемые`	`Массив`, `Неопределено`	`Неопределено`	Шаблоны ключей исключаемых атрибутов, приоритетнее включаемых

bsl

Включаемые = Новый Массив();
Включаемые.Добавить("service.*");
Исключаемые = Новый Массив();
Исключаемые.Добавить("service.instance.id");
ПрометеусЧитатель.УстановитьАтрибутыРесурсаВЛейблах(Включаемые, Исключаемые);

СброситьБуфер / СброситьБуферБезОчистки

Совместимость с MetricReader: выгружать нечего (pull-модель).

Возвращает: ОтелРезультатЭкспорта — успех; после Закрыть — ошибка

Закрыть

Очищает зарегистрированные метры и продюсеры. После закрытия сбор возвращает пустой результат с ошибкой, сброс буфера — ошибку.

Возвращает: ОтелРезультатЗакрытия — успех; повторный вызов — ошибка «Reader закрыт»

ЛимитМощности

Возвращает лимит мощности (cardinality limit) читателя по умолчанию для всех видов инструментов. У каждого читателя свои потоки метрик, поэтому лимит действует только на данные этого читателя.

Возвращает: Число — 2000 (значение по умолчанию из спецификации)

ЛимитМощностиДляВида

Параметр	Тип	По умолчанию	Описание
`ВидИнструмента`	`Строка`	—	`Counter`, `Histogram`, `ObservableGauge`, ...

Возвращает: Число

УстановитьЛимитМощностиДляВида

Задаёт лимит мощности читателя для вида инструмента. Действует для инструментов, созданных после вызова.

Параметр	Тип	По умолчанию	Описание
`ВидИнструмента`	`Строка`	—	Вид инструмента
`Лимит`	`Число`	—	Лимит мощности

АгрегацияПоУмолчанию

Возвращает агрегацию читателя по умолчанию для вида инструмента (агрегация по умолчанию настраивается функцией вида инструмента). Применяется к потокам, для которых View не задал агрегацию.

Параметр	Тип	По умолчанию	Описание
`ВидИнструмента`	`Строка`	—	Вид инструмента

Возвращает: Строка, Соответствие — заданная агрегация; "default" — агрегация спецификации для вида

УстановитьАгрегациюПоУмолчанию

Задаёт агрегацию читателя по умолчанию для вида инструмента. Действует для инструментов, созданных после вызова.

Параметр	Тип	По умолчанию	Описание
`ВидИнструмента`	`Строка`	—	Вид инструмента
`Агрегация`	`Строка`, `Соответствие`	—	Агрегация (`ОтелАгрегация.Сумма()`, `"drop"`, ...)

bsl

ПрометеусЧитатель = Новый ОтелПрометеусЧитательМетрик();
ПрометеусЧитатель.УстановитьАгрегациюПоУмолчанию("UpDownCounter", "drop");

АгрегацияГистограммПоУмолчанию

Возвращает агрегацию гистограмм по умолчанию для этого читателя.

Возвращает: Строка, Соответствие — заданная для вида Histogram через УстановитьАгрегациюПоУмолчанию или "explicit_bucket_histogram"

ВременнаяАгрегацияДляВида

Возвращает временную агрегацию потоков читателя: Prometheus принимает только кумулятивные данные.

Параметр	Тип	По умолчанию	Описание
`ВидИнструмента`	`Строка`	—	Вид инструмента

Возвращает: ОтелВременнаяАгрегация.Кумулятивная()

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

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

Запустить — ничего не делает: у ОтелПериодическийЧитательМетрик метод запускает фоновый сбор, а pull-читателю запускать нечего — метрики собираются по запросу;
ЗарегистрироватьУПровайдера — регистрирует читатель у провайдера при его создании и запоминает ресурс провайдера для продюсеров метрик. Читатель регистрируется только у одного провайдера: повторный вызов пишет ошибку в лог и возвращает Ложь, и провайдер такой читатель не добавляет.

Пример

bsl

// Настройка Prometheus-читателя
ПрометеусЧитатель = Новый ОтелПрометеусЧитательМетрик();

Построитель = Новый ОтелПостроительПровайдераМетрик();
Построитель.ЗарегистрироватьЧитатель(ПрометеусЧитатель);
Провайдер = Построитель.Построить();

// В HTTP-обработчике /metrics
ТелоОтвета = ПрометеусЧитатель.СобратьВТексте();
ТипКонтента = ПрометеусЧитатель.ContentType(); // "text/plain; version=0.0.4; charset=utf-8"

ОтелРеверсивныйСчетчик

Реверсивный счётчик (UpDownCounter) — инструмент для суммирования значений, допускающий уменьшение.

Описание

ОтелРеверсивныйСчетчик реализует спецификацию OpenTelemetry UpDownCounter. Принимает любые значения, включая отрицательные. Используется для измерений, которые могут как расти, так и уменьшаться (количество активных соединений, размер очереди и т.д.). Все методы безопасны для конкурентного вызова из нескольких потоков.

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

Методы

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

Добавить

Добавляет значение к счётчику. Принимает и отрицательные значения.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Значение для добавления (может быть отрицательным)
`Атрибуты`	`ОтелАтрибуты`	`Неопределено`	Атрибуты точки данных
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Явный контекст

Включен

Проверяет, включён ли инструмент — записывает ли он измерения (спецификация Metrics API, раздел Enabled). У выключенного инструмента Добавить ничего не записывает, поэтому по результату можно не вычислять атрибуты и значение измерения.

Возвращает Ложь, если:

инструмент отключён закрытием провайдера: Закрыть() провайдера отключает инструменты его метров, в том числе созданные после закрытия;
инструмент создан no-op метром: его выдаёт закрытый провайдер и no-op провайдер, пока SDK не настроен;
все потоки инструмента используют агрегацию Drop (ОтелАгрегация.Отбросить()): её задаёт View или агрегация читателя по умолчанию для вида инструмента.

Иначе возвращает Истина.

Параметр	Тип	По умолчанию	Описание
`Атрибуты`	`ОтелАтрибуты`, `Неопределено`	`Неопределено`	Зарезервирован для будущих версий, на результат не влияет

Возвращает: Булево — Истина, если инструмент записывает измерения

Вид

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

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

Имя

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

Описание

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

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

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

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

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

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

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

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

Собрать — возвращает данные первого потока инструмента, не начиная новый интервал сбора;
ОчиститьТочкиДанных — завершает интервал сбора всех потоков: при дельта-временности начинает новый интервал, при кумулятивной сбрасывает exemplars;
КоличествоСерий — возвращает количество серий атрибутов первого потока;
УстановитьЛимитМощности — задаёт лимит мощности всех потоков (потокам метра его задают View, читатель или сам метр);
УстановитьФильтрЭкземпляров — задаёт фильтр exemplars всех потоков (потокам метра его задаёт провайдер);
УстановитьФабрикуРезервуаров — задаёт фабрику резервуаров exemplars всех потоков;
УстановитьРезервуарЭкземпляров — устаревший вариант: один резервуар exemplars на все серии потока, пишет предупреждение в лог;
УстановитьРазрешенныеКлючиАтрибутов, УстановитьИсключенныеКлючиАтрибутов — задают фильтр ключей атрибутов всех потоков (потокам метра его задаёт View).

Пример

bsl

АктивныеСоединения = Метр.СоздатьРеверсивныйСчетчик(
    "db.connections.active", "Активные соединения с БД");

// Новое соединение
АктивныеСоединения.Добавить(1);

// Соединение закрыто
АктивныеСоединения.Добавить(-1);

ОтелРегистрацияНаблюдателя

Токен регистрации наблюдателя — позволяет отменить регистрацию callback.

Описание

ОтелРегистрацияНаблюдателя возвращают:

ДобавитьCallback асинхронного инструмента — токен связывает инструмент с добавленным callback;
ОтелМетр.ЗарегистрироватьОбратныйВызов — токен связывает метр с регистрацией callback нескольких инструментов. Если регистрация отклонена (нет инструментов, инструмент синхронный или создан другим метром), возвращается токен, Закрыть() которого ничего не делает.

Закрыть() отменяет регистрацию.

Конструктор

Параметр	Тип	Описание
`Инструмент`	`ОтелБазовыйНаблюдаемыйИнструмент`, `ОтелМетр`	Владелец регистрации (объект с методом `УдалитьCallback`)
`Действие`	`Действие`, `Структура`	Зарегистрированный callback или регистрация мульти-callback

Методы

Закрыть

Отменяет регистрацию. После вызова callback больше не вызывается при сборе метрик. Повторный вызов ничего не делает.

Эквивалентно вызову Инструмент.УдалитьCallback(Действие).

Возвращает: Неопределено

Пример

bsl

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

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

// ... некоторое время работы ...

// Отменить callback-и (например, при завершении работы модуля)
Регистрация.Закрыть();
РегистрацияМульти.Закрыть();

ОтелРезервуарЭкземпляров

Простой резервуар exemplars фиксированного размера (SimpleFixedSizeExemplarReservoir); его методы — контракт своего резервуара.

Описание

Резервуар exemplars (ExemplarReservoir) отбирает exemplars одной серии потока метрики. SDK предлагает резервуару измерения серии методом Предложить, а при сборе забирает отобранные exemplars методом Собрать и добавляет их в точку данных серии — в ключ exemplars (формат — в ОтелДанныеМетрики).

ОтелРезервуарЭкземпляров — встроенный простой резервуар. Его создаёт ОтелФабрикаПростыхРезервуаров: SDK использует эту фабрику по умолчанию для большинства агрегаций (см. Резервуар по умолчанию), а приложение передаёт её в представление, чтобы задать размер. Как резервуар отбирает измерения, на какой интервал создаётся и что попадает в exemplar, описано на странице фабрики. Напрямую резервуар создают, например, в своём резервуаре, чтобы поручить встроенному отбор и формирование exemplars (см. Пример).

Резервуар хранит exemplars и счётчик измерений отдельно для каждого ключа серии (КлючАтрибутов), поэтому один объект может обслуживать несколько серий; резервуар, созданный фабрикой, получает измерения одной серии. Методы безопасны для одновременного вызова из нескольких потоков (спецификация Metrics SDK, раздел Concurrency requirements): данные резервуара защищены блокировкой.

Свой резервуар подключают так же — фабрикой в представлении. Что для этого нужно реализовать, описано в разделе Свой резервуар.

Другие резервуары SDK

Те же методы реализуют резервуары двух других фабрик SDK:

ОтелВыровненныйРезервуарГистограммы — его создаёт ОтелФабрикаВыровненныхРезервуаровГистограммы, конструктор — Новый ОтелВыровненныйРезервуарГистограммы(Границы) с обязательным массивом границ бакетов. Хранит не больше одного exemplar на бакет гистограммы: МаксРазмер() возвращает число границ плюс один, Предложить кладёт exemplar в слот бакета, в который попадает значение, Собрать возвращает заполненные слоты в порядке бакетов. Ключи exemplar те же; как резервуар отбирает измерения внутри бакета — на странице фабрики.
ОтелНоопРезервуарЭкземпляров — его создаёт ОтелФабрикаNoopРезервуаров, конструктор без параметров. Предложить и Очистить ничего не делают, Собрать возвращает пустой массив. Метода МаксРазмер у него нет.

Конструктор

bsl

Новый ОтелРезервуарЭкземпляров(МаксРазмер)

Параметр	Тип	По умолчанию	Описание
`МаксРазмер`	`Число`	`1`	Сколько exemplars резервуар хранит для одного ключа серии

Методы

МаксРазмер

Возвращает размер резервуара — значение МаксРазмер из конструктора. SDK метод не вызывает.

Возвращает: Число

Предложить

Предлагает резервуару измерение. SDK вызывает метод для каждого измерения серии, которое пропустил фильтр exemplars провайдера; что SDK передаёт в параметрах — в разделе Параметры Предложить.

Резервуар решает, сохранить ли измерение, до того как создаёт exemplar (спецификация Metrics SDK, раздел ExemplarReservoir: при отборе резервуару следует избегать выделения памяти). Первые МаксРазмер измерений ключа сохраняются подряд, далее N-е измерение ключа с вероятностью МаксРазмер/N заменяет случайно выбранный exemplar (Algorithm R). Сохранённый exemplar — Соответствие с ключами:

timeUnixNano — Timestamp, а если он не передан — время вызова;
asDouble — Значение;
traceId и spanId — ID из КонтекстСпана; без него — из спана контекста Контекст, если контекст этого спана валиден. Текущий контекст резервуар сам не читает: без обоих параметров ID в exemplar нет;
filteredAttributes — атрибуты АтрибутыИзмерения, ключей которых нет в АтрибутыСерии, в формате OTLP. Если таких атрибутов нет, ключа нет.

Параметр	Тип	По умолчанию	Описание
`КлючАтрибутов`	`Строка`	—	Ключ серии: exemplars и счётчик измерений у каждого ключа свои
`Значение`	`Число`	—	Значение измерения
`АтрибутыИзмерения`	`ОтелАтрибуты`, `Неопределено`	`Неопределено`	Все атрибуты измерения
`АтрибутыСерии`	`ОтелАтрибуты`, `Неопределено`	`Неопределено`	Атрибуты серии — атрибуты измерения, которые сохранил поток метрики
`КонтекстСпана`	`ОтелКонтекстСпана`, `Неопределено`	`Неопределено`	Контекст спана, в котором записано измерение
`Timestamp`	`Строка`, `Неопределено`	`Неопределено`	Время измерения — строка с числом наносекунд от начала эпохи Unix
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Контекст измерения (Context)

Собрать

Возвращает exemplars ключа серии. Массив новый: следующие вызовы Предложить его не меняют. Резервуар при этом не очищается: exemplars и счётчик измерений ключа сохраняются, и повторный вызов вернёт те же exemplars, пока новые измерения их не заменят.

Параметр	Тип	По умолчанию	Описание
`КлючАтрибутов`	`Строка`	—	Ключ серии, как в `Предложить`

Возвращает: Массив из Соответствие — exemplars (ключи — в описании Предложить); пустой массив, если у ключа их нет

Очистить

Удаляет exemplars и счётчики измерений всех ключей: отбор начинается заново. У резервуаров, созданных фабрикой, SDK метод не вызывает — на новый интервал сбора серия получает новый резервуар. Общий резервуар, заданный устаревшим УстановитьРезервуарЭкземпляров, SDK очищает при каждом сборе потока, кумулятивном и дельта: exemplars точки относятся к интервалу с прошлого сбора.

Свой резервуар

Свой резервуар (спецификация Metrics SDK, раздел Custom ExemplarReservoir) подключают через представление. В параметр РезервуарЭкземпляров конструктора ОтелПредставление передают фабрику — объект с функцией СоздатьРезервуар() без параметров, которая на каждый вызов возвращает новый резервуар. Представление регистрируют методом ЗарегистрироватьПредставление(Селектор, Представление)построителя провайдера или работающего провайдера. Фабрика и резервуар — обычные классы приложения: интерфейса для них в библиотеке нет, SDK вызывает методы по имени.

Методы резервуара

У резервуара, созданного фабрикой, SDK вызывает только два метода — с теми же сигнатурами, что у ОтелРезервуарЭкземпляров:

Предложить — для каждого измерения серии, которое пропустил фильтр exemplars провайдера (ОтелФильтрЭкземпляров). Проверять фильтр резервуару не нужно;
Собрать(КлючАтрибутов) — при каждом сборе потока метрики, один раз для каждой серии, даже если резервуару ничего не предлагалось.

Очистить и МаксРазмер у таких резервуаров SDK не вызывает, реализовывать их не нужно. Очистить SDK вызывает только у одного общего резервуара, заданного инструменту устаревшим методом УстановитьРезервуарЭкземпляров, а МаксРазмер не вызывает вовсе.

Объявляйте Предложить с семью параметрами и значениями по умолчанию, как у ОтелРезервуарЭкземпляров: синхронные инструменты передают все семь параметров, асинхронные — только первые четыре. Если у параметров с пятого по седьмой нет значений по умолчанию, вызов от асинхронного инструмента завершается ошибкой о недостаточном числе параметров. SDK пишет её в лог только на уровне отладки, и exemplars асинхронных инструментов пропадают незаметно.

Параметры Предложить

Параметр	Синхронные инструменты	Асинхронные инструменты
`КлючАтрибутов`	Ключ серии — `Ключ()` её атрибутов; пустая строка у серии без атрибутов, служебный ключ у серии переполнения. Один и тот же во всех вызовах одного резервуара	Так же
`Значение`	Значение из `Добавить` или `Записать`	Значение наблюдения
`АтрибутыИзмерения`	Атрибуты из `Добавить` или `Записать` — тот же объект, что передало приложение; `Неопределено`, если атрибуты не переданы	Атрибуты наблюдения; пустой `ОтелАтрибуты`, если наблюдение записано без атрибутов
`АтрибутыСерии`	Атрибуты серии после фильтра атрибутов потока (`РазрешенныеКлючиАтрибутов` и `ИсключенныеКлючиАтрибутов` представления) — копия, сделанная при создании серии; `Неопределено`, если измерение записано без атрибутов. У серии переполнения — один атрибут `otel.metric.overflow` со значением `Истина`	Атрибуты серии после фильтра атрибутов потока — копия; у серии переполнения — `otel.metric.overflow`
`КонтекстСпана`	Контекст спана из `Контекст`, а если `Контекст` не передан — текущего спана потока, который записывает измерение; `Неопределено`, если спана нет или его контекст невалиден	Не передаётся
`Timestamp`	Всегда `Неопределено`: время exemplar резервуар определяет сам	Не передаётся
`Контекст`	Контекст, переданный приложением в `Добавить` или `Записать`; `Неопределено`, если не передан	Не передаётся

Атрибуты измерения резервуар получает целиком вместе с атрибутами серии: так exemplar может сохранить атрибуты, которых нет в серии (спецификация Metrics SDK, раздел ExemplarReservoir). Не храните ссылку на АтрибутыИзмерения: приложение может изменить объект после записи, поэтому нужное переводите в exemplar сразу.

Асинхронные инструменты предлагают резервуару наблюдения при сборе: фильтр exemplars для них проверяет текущий контекст потока, который выполняет сбор, а контекст спана резервуар не получает.

Когда SDK создаёт резервуар

SDK вызывает СоздатьРезервуар() для каждой новой серии каждого потока метрики. Потоки отдельные у каждого читателя и у каждого представления, выбравшего инструмент, поэтому одно измерение может попасть в несколько резервуаров. Резервуар служит одному интервалу сбора:

у синхронного инструмента серия получает резервуар при первом измерении в интервале. После сбора читателем при дельта-временности интервал начинается без серий, и резервуар создаётся при следующем измерении серии, а при кумулятивной все серии потока получают новые резервуары сразу после сбора;
у асинхронного инструмента серии и их резервуары создаются при каждом сборе — для наборов атрибутов, которые наблюдались в этом сборе.

Поэтому всё, что отобрал резервуар, относится к интервалу точки данных (спецификация Metrics SDK, раздел ExemplarReservoir). С фильтром ОтелФильтрЭкземпляров.ВсегдаВыключен() и у потоков с агрегацией drop резервуары серий не создаются.

Кроме того, SDK вызывает СоздатьРезервуар(), чтобы проверить фабрику, — при создании инструмента и при каждом новом разрешении его потоков, например после регистрации представления в работающем провайдере (см. Проверка фабрики). Созданный так резервуар не используется, а проверка выполняется и с фильтром ВсегдаВыключен().

Фабрику одного представления SDK использует во всех его потоках метрики — у всех выбранных инструментов и всех читателей. Поэтому СоздатьРезервуар() должен быть быстрым, без побочных эффектов и безопасным для одновременного вызова из нескольких потоков. Возвращайте новый объект на каждый вызов (резервуар создаётся для каждой серии — спецификация Metrics SDK, раздел Custom ExemplarReservoir): резервуар, общий для нескольких серий, SDK не очищает между интервалами и может вызывать одновременно из разных потоков.

Проверка фабрики

Проверяя фабрику, SDK вызывает СоздатьРезервуар() у объекта из параметра РезервуарЭкземпляров. Если вызов завершился исключением — метода нет или он сам выбросил исключение, — объект отклоняется: в лог oscript.lib.opentelemetry.metrics пишется ошибка «Резервуар exemplars View для инструмента '<имя>' не является фабрикой (нет метода СоздатьРезервуар): резервуар создается на каждую серию, используется резервуар по умолчанию». Текст один и тот же в обоих случаях, исходная ошибка в лог не попадает. Так отклоняется и резервуар, переданный вместо фабрики, например ОтелРезервуарЭкземпляров. Остальные настройки представления применяются, а поток получает резервуар по умолчанию для своей агрегации (см. Резервуар по умолчанию).

Что возвращает СоздатьРезервуар() и есть ли у резервуара нужные методы, SDK не проверяет: ошибки проявятся при вызовах.

Потоки и исключения

SDK не вызывает методы одного резервуара одновременно:

у синхронного инструмента Предложить выполняется в потоке, который записывает измерение, под блокировкой потока метрики. Пока работает Предложить, другие измерения этого потока метрики ждут, поэтому метод должен быть быстрым — без ввода-вывода и ожиданий. Собрать при кумулятивном сборе выполняется под той же блокировкой, а при дельта-сборе — после закрытия интервала, когда новых вызовов Предложить у резервуара уже не будет;
у асинхронного инструмента Предложить и Собрать вызываются по очереди в потоке, который выполняет сбор.

Вызовы одного резервуара приходят из разных потоков — потоков приложения и потока сбора, — но не одновременно, поэтому резервуару, который фабрика создаёт на каждый вызов, своя блокировка не нужна. Блокировка нужна, если резервуар обращается к общим данным, например к полям фабрики.

Исключения:

из Предложить SDK перехватывает и пишет в лог на уровне отладки: «Ошибка при захвате exemplar: …». Измерение агрегируется, exemplar не сохраняется;
из Собрать — SDK перехватывает и пишет в лог предупреждение «Exemplars потока метрики '<имя>' не собраны: ошибка резервуара: …». Точка данных серии выдаётся без exemplars, остальные данные сбора не меняются. Так же действует результат, который нельзя обойти циклом Для Каждого; Неопределено вместо пустого массива SDK считает отсутствием exemplars и в лог не пишет;
из СоздатьРезервуар() — при проверке отклоняет фабрику. При создании серии и при замене резервуара после кумулятивного сбора SDK пишет в лог предупреждение «Резервуар exemplars потока метрики '<имя>' не создан: …», серия остаётся без резервуара до следующего интервала сбора: измерения агрегируются, exemplars не сохраняются;
из Очистить общего резервуара — SDK пишет в лог предупреждение «Резервуар exemplars потока метрики '<имя>' не очищен и отключен: …» и отключает резервуар, чтобы точки не получили exemplars прошлых интервалов. Сбор продолжается, точки потока выдаются без exemplars.

Что возвращает Собрать

Собрать возвращает Массив exemplars серии; пустой массив — у точки данных нет exemplars. SDK копирует массив, поэтому можно вернуть свой внутренний, а сами exemplars кладёт в точку данных без проверок и изменений: OTLP-экспортёр передаёт их как есть. Поэтому exemplar — Соответствие с ключами OTLP JSON, как у встроенных резервуаров: timeUnixNano, asDouble, traceId и spanId, filteredAttributes (типы — в ОтелДанныеМетрики, откуда брать значения — в описании Предложить).

Время SDK не передаёт: берите текущее — ОтелУтилиты.ТекущееВремяВНаносекундах(). Атрибуты измерения, которых нет в атрибутах серии, exemplar должен сохранить в filteredAttributes (спецификация Metrics SDK, раздел ExemplarReservoir); массив атрибутов в формате OTLP возвращает ВМассивOtlp() объекта ОтелАтрибуты.

Пример

Резервуар, который хранит exemplar измерения с наибольшим значением — например, самого медленного запроса за интервал, — класс приложения в файле РезервуарМаксимума.os:

bsl

// Резервуар exemplars одной серии: хранит измерение с наибольшим значением.
// SDK вызывает методы одного резервуара по очереди, блокировка не нужна.

// Число, Неопределено - наибольшее предложенное значение
Перем Максимум;
// Соответствие, Неопределено - exemplar этого измерения
Перем Экземпляр;

Процедура Предложить(КлючАтрибутов, Значение, АтрибутыИзмерения = Неопределено,
        АтрибутыСерии = Неопределено, КонтекстСпана = Неопределено,
        Timestamp = Неопределено, Контекст = Неопределено) Экспорт

    Если Максимум <> Неопределено И Значение <= Максимум Тогда
        Возврат;
    КонецЕсли;
    Максимум = Значение;

    Экземпляр = Новый Соответствие();
    Экземпляр.Вставить("timeUnixNano", ОтелУтилиты.ТекущееВремяВНаносекундах());
    Экземпляр.Вставить("asDouble", Значение);
    Если КонтекстСпана <> Неопределено Тогда
        Экземпляр.Вставить("traceId", КонтекстСпана.ИдТрассировки());
        Экземпляр.Вставить("spanId", КонтекстСпана.ИдСпана());
    КонецЕсли;

    // Атрибуты измерения, которых нет в атрибутах серии
    Отфильтрованные = Новый ОтелАтрибуты();
    Если АтрибутыИзмерения <> Неопределено Тогда
        Для Каждого КлючИЗначение Из АтрибутыИзмерения.ВСоответствие() Цикл
            Если АтрибутыСерии = Неопределено
                    ИЛИ АтрибутыСерии.Получить(КлючИЗначение.Ключ) = Неопределено Тогда
                Отфильтрованные.Установить(КлючИЗначение.Ключ, КлючИЗначение.Значение);
            КонецЕсли;
        КонецЦикла;
    КонецЕсли;
    Если Отфильтрованные.Количество() > 0 Тогда
        Экземпляр.Вставить("filteredAttributes", Отфильтрованные.ВМассивOtlp());
    КонецЕсли;

КонецПроцедуры

Функция Собрать(КлючАтрибутов) Экспорт
    Результат = Новый Массив();
    Если Экземпляр <> Неопределено Тогда
        Результат.Добавить(Экземпляр);
    КонецЕсли;
    Возврат Результат;
КонецФункции

Фабрика — класс в файле ФабрикаРезервуаровМаксимума.os:

bsl

// Фабрика резервуаров exemplars: новый резервуар на каждый вызов.

Функция СоздатьРезервуар() Экспорт
    Возврат Новый РезервуарМаксимума();
КонецФункции

Подключение к гистограмме длительности запросов:

bsl

#Использовать opentelemetry

Каталог = ТекущийСценарий().Каталог;
ПодключитьСценарий(ОбъединитьПути(Каталог, "РезервуарМаксимума.os"), "РезервуарМаксимума");
ПодключитьСценарий(ОбъединитьПути(Каталог, "ФабрикаРезервуаровМаксимума.os"), "ФабрикаРезервуаровМаксимума");

Экспортер = Новый ОтелЭкспортерМетрик(Новый ОтелHttpТранспорт("http://localhost:4318"));

Представление = Новый ОтелПредставление(, , , , , ,
    Новый ФабрикаРезервуаровМаксимума()); // РезервуарЭкземпляров

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ЗарегистрироватьЧитатель(Новый ОтелПериодическийЧитательМетрик(Экспортер))
    .ЗарегистрироватьПредставление(Новый ОтелСелекторИнструментов("http.server.request.duration"), Представление)
    .Построить();

Метр = Провайдер.ПолучитьМетр("my-app");
Гистограмма = Метр.СоздатьГистограмму("http.server.request.duration", "Длительность запросов", "s");

// Exemplar сохраняется для измерений в контексте сэмплированного спана:
// фильтр exemplars по умолчанию - ОтелФильтрЭкземпляров.ПоТрассировке()
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("http.route", "/orders");
Гистограмма.Записать(0.75, Атрибуты);

Резервуар может не формировать exemplars сам, а передавать отобранные измерения встроенному. Резервуар медленных запросов — файл РезервуарМедленных.os; фабрика к нему такая же, как ФабрикаРезервуаровМаксимума, но возвращает Новый РезервуарМедленных():

bsl

// ОтелРезервуарЭкземпляров - до трех exemplars из запросов не короче секунды
Перем Резервуар;

Процедура Предложить(КлючАтрибутов, Значение, АтрибутыИзмерения = Неопределено,
        АтрибутыСерии = Неопределено, КонтекстСпана = Неопределено,
        Timestamp = Неопределено, Контекст = Неопределено) Экспорт
    Если Значение >= 1 Тогда
        Резервуар.Предложить(КлючАтрибутов, Значение, АтрибутыИзмерения, АтрибутыСерии,
            КонтекстСпана, Timestamp, Контекст);
    КонецЕсли;
КонецПроцедуры

Функция Собрать(КлючАтрибутов) Экспорт
    Возврат Резервуар.Собрать(КлючАтрибутов);
КонецФункции

Процедура ПриСозданииОбъекта()
    Резервуар = Новый ОтелРезервуарЭкземпляров(3);
КонецПроцедуры

См. также

ОтелРезультатПроизводстваМетрик

Результат Произвести продюсера метрик: статус и произведённые метрики.

Описание

Продюсер метрик (ИнтерфейсПродюсерМетрик) возвращает этот объект из Произвести: так читатель узнаёт, произведены ли метрики, завершилось ли производство ошибкой или не уложилось в таймаут (спецификация Metrics SDK, раздел Produce batch: Produce SHOULD provide a way to let the caller know whether it succeeded, failed or timed out).

Статус — строка:

Статус	Константа	Что делает читатель
`"Success"`	`СтатусУспех()`	Добавляет `Метрики` к данным сбора
`"Failure"`	`СтатусОшибка()`	Пишет в лог предупреждение со статусом и `СообщениеОшибки`, метрики не использует; результат сбора — ошибка
`"Timeout"`	`СтатусТаймаут()`	Пишет в лог предупреждение, метрики не использует; результат сбора — таймаут, если других сбоев нет

Другой статус читатель считает ошибкой, как "Failure".

Константы статусов — методы объекта, поэтому в конструктор статус передают строкой. Поля результата — экспортные переменные: их можно задать и после создания объекта.

Конструктор

bsl

Новый ОтелРезультатПроизводстваМетрик(НачальныйСтатус, НачальныеМетрики, НачальноеСообщение)

Параметр	Тип	По умолчанию	Описание
`НачальныйСтатус`	`Строка`	`"Success"`	Статус: `"Success"`, `"Failure"` или `"Timeout"`
`НачальныеМетрики`	`Массив из ОтелДанныеМетрики`, `Неопределено`	`Неопределено`	Произведённые метрики (ОтелДанныеМетрики); `Неопределено` — пустой массив
`НачальноеСообщение`	`Строка`	`""`	Сообщение об ошибке для статусов `"Failure"` и `"Timeout"`

Свойства

Свойство	Тип	По умолчанию	Описание
`Статус`	`Строка`	`"Success"`	Статус результата
`Метрики`	`Массив из ОтелДанныеМетрики`	пустой массив	Произведённые метрики; читатель берёт их только при статусе `"Success"`
`СообщениеОшибки`	`Строка`	`""`	Сообщение об ошибке; читатель пишет его в лог

Методы

СтатусУспех

Возвращает константу статуса успешного производства.

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

СтатусОшибка

Возвращает константу статуса ошибки.

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

СтатусТаймаут

Возвращает константу статуса таймаута: продюсер не уложился в отведённое время.

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

Успех

Проверяет, что производство успешно. Так читатели проверяют результат продюсера.

Возвращает: Булево — Истина, если Статус равен "Success"

Пример

bsl

// Успех: метрики продюсера
Метрики = Новый Массив();
Метрики.Добавить(Данные); // ОтелДанныеМетрики
Результат = Новый ОтелРезультатПроизводстваМетрик("Success", Метрики);

// Ошибка источника
Результат = Новый ОтелРезультатПроизводстваМетрик("Failure", , "Источник метрик недоступен");

// Таймаут: статус по константе объекта
Результат = Новый ОтелРезультатПроизводстваМетрик();
Результат.Статус = Результат.СтатусТаймаут();
Результат.СообщениеОшибки = "Источник не ответил в срок";

// Проверка результата, например в тесте продюсера
Результат = Продюсер.Произвести(Новый ОтелРесурс(), 0);
Если Результат.Успех() Тогда
    Для Каждого Данные Из Результат.Метрики Цикл
        Сообщить(Данные.Имя());
    КонецЦикла;
Иначе
    Сообщить(Результат.Статус + ": " + Результат.СообщениеОшибки);
КонецЕсли;

См. также

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

Модуль селекторов временной агрегации (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_PREFERENCE`	`temporality_preference`
`ВсегдаКумулятивная`	`cumulative` (по умолчанию)	`cumulative` (по умолчанию)
`ПредпочтительноДельта`	`delta`	`delta`
`НизкоеПотреблениеПамяти`	`lowmemory`	`low_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 (синхронные счётчик и гистограммы, включая экспоненциальную), кумулятивная агрегация — для остальных типов. Дельта-потоки синхронных инструментов не хранят серии между сборами.

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

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

Пример

bsl

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

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

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

bsl

// Дельта только для гистограмм
Функция Применить(ТипИнструмента) Экспорт
    Если ТипИнструмента = "histogram" Тогда
        Возврат ОтелВременнаяАгрегация.Дельта();
    КонецЕсли;
    Возврат ОтелВременнаяАгрегация.Кумулятивная();
КонецФункции

bsl

ПодключитьСценарий("СелекторДельтаГистограмм.os", "СелекторДельтаГистограмм");
Экспортер = Новый ОтелЭкспортерМетрик(Транспорт, Новый СелекторДельтаГистограмм());

См. также

ОтелСелекторИнструментов

Селектор инструментов (InstrumentSelector) — критерии, по которым представление (View) выбирает инструменты.

Описание

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

Критерии селектора:

Критерий	С чем сравнивается	Сравнение
`Имя`	имя инструмента	без учёта регистра; `"*"` — любой инструмент
`ТипИнструмента`	вид инструмента	точное, с учётом регистра
`ИмяМетра`	имя метра — имя инструментирующей библиотеки из `ПолучитьМетр`	точное, с учётом регистра
`Единица`	единица измерения инструмента	точное, с учётом регистра (`ms` и `MS` — разные единицы)
`ВерсияМетра`	версия метра	точное, с учётом регистра
`АдресСхемыМетра`	адрес схемы метра	точное, с учётом регистра

Незаданный критерий (Неопределено) пропускает любые инструменты. Заданные критерии объединяются по «И»: селектор выбирает инструмент, только если совпали все заданные критерии. Селектор без критериев выбирает все инструменты.

Шаблонов в критериях нет. Особое значение имеет только имя "*" целиком; * и ? внутри имени — обычные символы: селектор "http.*" выбирает только инструмент с именем http.*, а не все инструменты с префиксом http..

Вид инструмента — строка: Counter, UpDownCounter, Histogram, Gauge, ObservableCounter, ObservableUpDownCounter, ObservableGauge. Единица инструмента, созданного без единицы измерения, — пустая строка.

Если View задаёт НовоеИмя, селектор должен выбирать не больше одного инструмента, иначе несколько инструментов получат одно имя метрики (спецификация Metrics SDK, раздел View). Для такого View с селектором без точного имени (Имя не задано или "*") метр пишет предупреждение в лог. Если потоки одного читателя всё же получили одно имя, все они экспортируются, в лог пишется предупреждение о конфликте идентичности метрик.

Критерии ТипИнструмента и Единица разводят одноимённые инструменты разного вида или единицы: при такой повторной регистрации метр пишет в лог предупреждение и советует View с селектором по имени и виду (или единице) и новым именем метрики.

Конструктор

bsl

Новый ОтелСелекторИнструментов(Имя, ТипИнструмента, ИмяМетра, Единица, ВерсияМетра, АдресСхемыМетра)

Все параметры необязательные.

Параметр	Тип	По умолчанию	Описание
`Имя`	`Строка`	`Неопределено`	Имя инструмента без учёта регистра; `"*"` — любой инструмент
`ТипИнструмента`	`Строка`	`Неопределено`	Вид инструмента: `Counter`, `Histogram`, `ObservableGauge`, ...
`ИмяМетра`	`Строка`	`Неопределено`	Имя метра (инструментирующей библиотеки)
`Единица`	`Строка`	`Неопределено`	Единица измерения инструмента
`ВерсияМетра`	`Строка`	`Неопределено`	Версия метра
`АдресСхемыМетра`	`Строка`	`Неопределено`	Адрес схемы метра

Методы

Совпадает

Проверяет, выбирает ли селектор инструмент с указанными параметрами. SDK вызывает метод при разрешении потоков инструмента: передаёт имя, вид и единицу инструмента и имя, версию и адрес схемы его метра. Вызвать метод можно и самому, чтобы проверить селектор.

Параметр	Тип	По умолчанию	Описание
`ИмяИнструмента`	`Строка`	—	Имя инструмента
`ТипИнструмента`	`Строка`	`""`	Вид инструмента
`НовоеИмяМетра`	`Строка`	`""`	Имя метра
`ЕдиницаИнструмента`	`Строка`	`""`	Единица измерения инструмента
`НоваяВерсияМетра`	`Строка`	`""`	Версия метра
`НовыйАдресСхемыМетра`	`Строка`	`""`	Адрес схемы метра

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

Имя

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

Возвращает: Строка, Неопределено — имя или "*"; Неопределено, если критерий не задан

ТипИнструмента

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

Возвращает: Строка, Неопределено — вид инструмента (Counter, Histogram, ...); Неопределено, если критерий не задан

ИмяМетра

Возвращает критерий имени метра.

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

ВерсияМетра

Возвращает критерий версии метра.

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

Единица

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

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

АдресСхемыМетра

Возвращает критерий адреса схемы метра.

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

Пример

bsl

// Отбросить все инструменты библиотеки legacy-lib
СелекторБиблиотеки = Новый ОтелСелекторИнструментов("*", , "legacy-lib");
Отбросить = Новый ОтелПредставление(, , , , ОтелАгрегация.Отбросить());

// Переименовать одну гистограмму: точное имя, вид и единица
СелекторЗадержки = Новый ОтелСелекторИнструментов("http.client.duration", "Histogram", , "ms");
Переименовать = Новый ОтелПредставление("http.client.duration.ms");

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ЗарегистрироватьЧитатель(Читатель)
    .ЗарегистрироватьПредставление(СелекторБиблиотеки, Отбросить)
    .ЗарегистрироватьПредставление(СелекторЗадержки, Переименовать)
    .Построить();

// Имя сравнивается без учёта регистра, единица - с учётом
Выбран = СелекторЗадержки.Совпадает("HTTP.Client.Duration", "Histogram", "my-lib", "ms"); // Истина
Выбран = СелекторЗадержки.Совпадает("http.client.duration", "Histogram", "my-lib", "s");  // Ложь

См. также

ОтелСчетчик

Счётчик (Counter) — монотонный инструмент для суммирования неотрицательных значений.

Описание

ОтелСчетчик реализует спецификацию OpenTelemetry Counter. Агрегирует значения суммой. Принимает только неотрицательные значения — отрицательные игнорируются с предупреждением. Все методы безопасны для конкурентного вызова из нескольких потоков.

Для значений, которые могут уменьшаться, используйте ОтелРеверсивныйСчетчик.

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

Методы

Добавить, Записать и Вид определены в самом классе, остальные методы унаследованы от ОтелБазовыйСинхронныйИнструмент.

Добавить

Добавляет значение к счётчику. Отрицательное значение и значение, которое не является числом, игнорируются с предупреждением в лог, исключение не бросается.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Неотрицательное значение для добавления
`Атрибуты`	`ОтелАтрибуты`	`Неопределено`	Атрибуты точки данных
`Контекст`	`Соответствие`, `Неопределено`	`Неопределено`	Явный контекст

Записать

То же, что Добавить. Метод есть у всех синхронных инструментов, у счётчика он тоже не принимает отрицательные значения. Параметры такие же, как у Добавить.

Включен

Возвращает Ложь, если:

инструмент отключён закрытием провайдера: Закрыть() провайдера отключает инструменты его метров, в том числе созданные после закрытия;
инструмент создан no-op метром: его выдаёт закрытый провайдер и no-op провайдер, пока SDK не настроен;
все потоки инструмента используют агрегацию Drop (ОтелАгрегация.Отбросить()): её задаёт View или агрегация читателя по умолчанию для вида инструмента.

Иначе возвращает Истина.

Параметр	Тип	По умолчанию	Описание
`Атрибуты`	`ОтелАтрибуты`, `Неопределено`	`Неопределено`	Зарезервирован для будущих версий, на результат не влияет

Возвращает: Булево — Истина, если инструмент записывает измерения

Вид

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

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

Имя

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

Описание

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

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

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

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

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

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

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

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

УстановитьЛог — подменяет логгер, в который счётчик пишет предупреждение об отрицательном значении;
Собрать — возвращает данные первого потока инструмента, не начиная новый интервал сбора;
ОчиститьТочкиДанных — завершает интервал сбора всех потоков: при дельта-временности начинает новый интервал, при кумулятивной сбрасывает exemplars;
КоличествоСерий — возвращает количество серий атрибутов первого потока;
УстановитьЛимитМощности — задаёт лимит мощности всех потоков (потокам метра его задают View, читатель или сам метр);
УстановитьФильтрЭкземпляров — задаёт фильтр exemplars всех потоков (потокам метра его задаёт провайдер);
УстановитьФабрикуРезервуаров — задаёт фабрику резервуаров exemplars всех потоков;
УстановитьРезервуарЭкземпляров — устаревший вариант: один резервуар exemplars на все серии потока, пишет предупреждение в лог;
УстановитьРазрешенныеКлючиАтрибутов, УстановитьИсключенныеКлючиАтрибутов — задают фильтр ключей атрибутов всех потоков (потокам метра его задаёт View).

Пример

bsl

Счетчик = Метр.СоздатьСчетчик("http.requests.total", "Всего HTTP-запросов");

// Без атрибутов
Счетчик.Добавить(1);

// С атрибутами
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("http.method", "GET");
Атрибуты.Установить("http.status_code", "200");
Счетчик.Добавить(1, Атрибуты);

// Дорогие атрибуты вычисляются, только если счётчик включён.
// Включен вызывается перед каждой записью: результат может измениться
Если Счетчик.Включен() Тогда
    Счетчик.Добавить(1, ВычислитьАтрибутыЗапроса());
КонецЕсли;

ОтелТипМетрики

Модуль констант типов метрик.

Описание

ОтелТипМетрики — глобальный модуль с константами строковых идентификаторов типов инструментов метрик. Используется при настройке представлений, экспорте и фильтрации.

Функции

Сумма

Возвращает строковый идентификатор типа Sum.

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

Датчик

Возвращает строковый идентификатор типа Gauge.

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

Гистограмма

Возвращает строковый идентификатор типа Histogram.

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

ЭкспоненциальнаяГистограмма

Возвращает строковый идентификатор типа ExponentialHistogram.

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

Сводка

Возвращает строковый идентификатор типа Summary. Инструменты SDK сводки не создают: их передают продюсеры метрик (MetricProducer), например мосты к другим библиотекам метрик. Точка данных сводки — Соответствие с ключами attributes, startTimeUnixNano, timeUnixNano, count, sum и quantileValues (массив соответствий с ключами quantile и value). OTLP-экспортёр передаёт сводки как summary, Prometheus-читатель — как Prometheus summary.

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

Пример

bsl

// Использование при создании представления для гистограмм
Если ТипМетрики = ОтелТипМетрики.Гистограмма() Тогда
    // Применить специальные настройки агрегации для гистограмм
    Представление = Новый ОтелПредставление(
        Неопределено, Неопределено, Неопределено, Неопределено,
        СтандартныеГраницы);
КонецЕсли;

ОтелФабрикаNoopРезервуаров

Фабрика пустых резервуаров exemplars: отключает exemplars потоков представления.

Описание

Фабрику передают в параметр РезервуарЭкземпляров представления. SDK вызывает СоздатьРезервуар() для каждой серии потока и получает пустой резервуар (ОтелНоопРезервуарЭкземпляров): он игнорирует предложенные измерения и ничего не собирает, поэтому у точек данных потока нет exemplars.

Так отключают exemplars отдельных инструментов. Например, атрибуты, которые представление убрало из потока (РазрешенныеКлючиАтрибутов, ИсключенныеКлючиАтрибутов), иначе попадают в exemplars как filteredAttributes. Фильтр ОтелФильтрЭкземпляров.ВсегдаВыключен() (ОтелФильтрЭкземпляров) отключает exemplars всех потоков провайдера (резервуары тогда не создаются вовсе), а эта фабрика — только потоков представления.

По умолчанию SDK эту фабрику не выбирает: у агрегации drop резервуаров нет, а остальные агрегации получают простые или выровненные по бакетам резервуары (см. раздел Резервуар по умолчанию).

Конструктор

bsl

Новый ОтелФабрикаNoopРезервуаров()

Без параметров.

Методы

СоздатьРезервуар

Создаёт новый пустой резервуар.

Возвращает: ОтелНоопРезервуарЭкземпляров — резервуар, который не хранит exemplars

Пример

bsl

// Атрибут user.id убран из потока; чтобы он не попал в exemplars как filteredAttributes,
// exemplars потока отключены
Исключенные = Новый Массив();
Исключенные.Добавить("user.id");

Представление = Новый ОтелПредставление(, , , , ,
    Исключенные,                          // ИсключенныеКлючиАтрибутов
    Новый ОтелФабрикаNoopРезервуаров());  // РезервуарЭкземпляров

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ЗарегистрироватьЧитатель(Читатель)
    .ЗарегистрироватьПредставление(Новый ОтелСелекторИнструментов("http.server.requests"), Представление)
    .Построить();

См. также

ОтелФабрикаВыровненныхРезервуаровГистограммы

Фабрика резервуаров exemplars, выровненных по бакетам гистограммы (AlignedHistogramBucketExemplarReservoir).

Описание

SDK использует эту фабрику по умолчанию для потоков с агрегацией явной гистограммы хотя бы с одной границей (больше одного бакета), с теми же границами, что у гистограммы потока. Резервуары других агрегаций перечислены в разделе Резервуар по умолчанию страницы ОтелФабрикаПростыхРезервуаров. Явно фабрику передают в параметр РезервуарЭкземпляровпредставления, например чтобы exemplars экспоненциальной гистограммы распределялись по заданным диапазонам значений.

SDK вызывает СоздатьРезервуар() для каждой серии потока (набора атрибутов точки данных): у каждой серии свой резервуар. Резервуар хранит exemplars одного интервала сбора: после сбора читателем серия получает новый резервуар.

Резервуар хранит не больше одного exemplar на бакет: слотов на один больше, чем границ, последний — для значений больше последней границы. Измерение попадает в бакет первой границы, которая не меньше значения: значение, равное границе, попадает в бакет этой границы, как в явной гистограмме. N-е измерение бакета заменяет сохранённый exemplar с вероятностью 1/N (равномерная выборка): у каждого измерения бакета за интервал равные шансы. Exemplar содержит то же, что у простого резервуара: значение, время, идентификаторы трассировки и спана и атрибуты измерения, которых нет в атрибутах серии (filteredAttributes).

Резервуару предлагаются только измерения, которые пропустил фильтр exemplars провайдера (ОтелФильтрЭкземпляров): по умолчанию — записанные в контексте сэмплированного спана. При фильтре ВсегдаВыключен() резервуары не создаются.

Границы должны идти по возрастанию: фабрика и резервуар их не сортируют. Чтобы exemplars совпадали с бакетами явной гистограммы, передайте те же границы, что у гистограммы потока.

Конструктор

bsl

Новый ОтелФабрикаВыровненныхРезервуаровГистограммы(Границы)

Параметр	Тип	По умолчанию	Описание
`Границы`	`Массив` из `Число`	—	Границы бакетов по возрастанию — в том же формате, что `ГраницыГистограммы` представления

Методы

СоздатьРезервуар

Создаёт новый резервуар с границами Границы. SDK вызывает метод для каждой серии потока на каждый интервал сбора.

Возвращает: ОтелВыровненныйРезервуарГистограммы — новый резервуар

Границы

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

Возвращает: Массив — массив, переданный в конструктор

Пример

bsl

// Экспоненциальная гистограмма задержки: exemplars по одному на диапазон значений
Границы = Новый Массив();
Границы.Добавить(0.1);
Границы.Добавить(0.5);
Границы.Добавить(1);

Представление = Новый ОтелПредставление(, , , ,
    ОтелАгрегация.ГистограммаЭкспоненциальная(),                  // Агрегация
    ,                                                             // ИсключенныеКлючиАтрибутов
    Новый ОтелФабрикаВыровненныхРезервуаровГистограммы(Границы)); // РезервуарЭкземпляров

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ЗарегистрироватьЧитатель(Читатель)
    .ЗарегистрироватьПредставление(Новый ОтелСелекторИнструментов("http.server.duration"), Представление)
    .Построить();

См. также

ОтелФабрикаПростыхРезервуаров

Фабрика простых резервуаров exemplars фиксированного размера (SimpleFixedSizeExemplarReservoir).

Описание

Фабрику передают в параметр РезервуарЭкземпляров представления, чтобы задать, сколько exemplars хранит точка данных потока. SDK вызывает СоздатьРезервуар() для каждой серии потока (набора атрибутов точки данных): у каждой серии свой резервуар. Резервуар хранит exemplars одного интервала сбора: после сбора читателем серия получает новый резервуар, поэтому exemplars точки взяты из измерений, записанных после предыдущего сбора.

Резервуар хранит не больше Размер exemplars. Первые Размер предложенных резервуару измерений сохраняются подряд, далее N-е измерение заменяет случайно выбранный exemplar с вероятностью Размер/N (равномерная выборка, Algorithm R): у каждого измерения интервала равные шансы попасть в exemplars.

Exemplar содержит значение измерения, время записи в резервуар, идентификаторы трассировки и спана, если измерение записано в контексте спана, и атрибуты измерения, которых нет в атрибутах серии (filteredAttributes), — например, отброшенные представлением через РазрешенныеКлючиАтрибутов или ИсключенныеКлючиАтрибутов. Наблюдения асинхронных инструментов предлагаются резервуару при сборе и идентификаторов трассировки и спана не содержат.

Резервуар по умолчанию

Если View не задал РезервуарЭкземпляров, фабрику выбирает SDK по агрегации потока (спецификация Metrics SDK, раздел Exemplar defaults):

Агрегация потока	Фабрика резервуаров
Явная гистограмма хотя бы с одной границей	ОтелФабрикаВыровненныхРезервуаровГистограммы с границами гистограммы
Экспоненциальная гистограмма	`ОтелФабрикаПростыхРезервуаров` размера min(20, `МаксБакетов`)
Отбросить (`drop`)	нет: у потока нет ни точек данных, ни exemplars
Сумма, последнее значение, явная гистограмма с пустым массивом границ	`ОтелФабрикаПростыхРезервуаров` размера 1

Конструктор

bsl

Новый ОтелФабрикаПростыхРезервуаров(Размер)

Параметр	Тип	По умолчанию	Описание
`Размер`	`Число`	`1`	Максимальное число exemplars в резервуаре серии

Методы

СоздатьРезервуар

Создаёт новый резервуар размера Размер. SDK вызывает метод для каждой серии потока на каждый интервал сбора.

Возвращает: ОтелРезервуарЭкземпляров — новый резервуар

Размер

Возвращает размер создаваемых резервуаров.

Возвращает: Число — максимальное число exemplars в резервуаре

Пример

bsl

// До пяти exemplars на точку данных счётчика запросов
Представление = Новый ОтелПредставление(, , , , , ,
    Новый ОтелФабрикаПростыхРезервуаров(5)); // РезервуарЭкземпляров

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ЗарегистрироватьЧитатель(Читатель)
    .ЗарегистрироватьПредставление(Новый ОтелСелекторИнструментов("http.server.requests"), Представление)
    .Построить();

См. также

ОтелФильтрЭкземпляров

Модуль фильтров exemplars (ExemplarFilter): какие измерения могут стать exemplars.

Описание

Exemplar — измерение, сохранённое вместе с точкой метрики: значение, время, ID трассировки и спана и атрибуты, которые отбросил фильтр атрибутов потока (формат — в ОтелДанныеМетрики). Фильтр решает, какие измерения предлагаются резервуару exemplars серии, а резервуар — какие из них сохранить (спецификация Metrics SDK, раздел ExemplarFilter).

Фильтр	Значение	`OTEL_METRICS_EXEMPLAR_FILTER`	Какие измерения предлагаются резервуару
`ВсегдаВключен()`	`1`	`always_on`	Все
`ВсегдаВыключен()`	`2`	`always_off`	Никакие: резервуары exemplars у серий не создаются
`ПоТрассировке()`	`3`	`trace_based`	Записанные в контексте сэмплированного спана

Фильтр один на провайдер метрик и действует на все его инструменты. По умолчанию — ПоТрассировке(). Задают фильтр:

методом УстановитьФильтрЭкземпляров ОтелПостроительПровайдераМетрик или третьим параметром конструктора ОтелПровайдерМетрик (Ресурс, Читатели, ФильтрЭкземпляров);
переменной окружения OTEL_METRICS_EXEMPLAR_FILTER: построитель провайдера читает её при создании, а УстановитьФильтрЭкземпляров заменяет это значение; конструктор ОтелПровайдерМетрик переменную не читает. Автоконфигурация берёт фильтр из того же параметра (otel.metrics.exemplar.filter). Пустое значение не меняет фильтр, нераспознанное — тоже, о нём пишется предупреждение в лог;
в файле конфигурации — значением exemplar_filter секции meter_provider (те же значения).

Фильтр провайдера возвращает его метод ФильтрЭкземпляров(). Выключить exemplars одного потока можно и без фильтра: резервуаром ОтелФабрикаNoopРезервуаров в представлении (ОтелПредставление).

Для ПоТрассировке() спан берётся из контекста измерения: явного параметра Контекст метода записи синхронного инструмента (Добавить, Записать), а без него — из текущего контекста. Спан должен быть валидным и сэмплированным (флаг sampled). У асинхронных инструментов фильтр применяется при сборе наблюдений, к текущему контексту потока, который выполняет сбор; ID трассировки и спана в их exemplars не попадают.

Функции

ВсегдаВключен

Возвращает фильтр AlwaysOn: резервуару предлагаются все измерения.

Возвращает: Число — 1

ВсегдаВыключен

Возвращает фильтр AlwaysOff: exemplars не собираются. Резервуары exemplars у серий не создаются, поэтому накладных расходов на exemplars нет.

Возвращает: Число — 2

ПоТрассировке

Возвращает фильтр TraceBased — фильтр по умолчанию: резервуару предлагаются измерения, записанные в контексте сэмплированного спана.

Возвращает: Число — 3

ИзСтроки

Возвращает фильтр по значению в формате OTEL_METRICS_EXEMPLAR_FILTER: always_on, always_off или trace_based, без учёта регистра и пробелов по краям. Так построитель провайдера и автоконфигурация разбирают значение переменной окружения; приложение может так же разобрать значение из своих настроек.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`, `Неопределено`	—	Значение фильтра

Возвращает: Число, Неопределено — константа фильтра; Неопределено, если значение не строка или не распознано

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

ДолженЗахватить — проверяет по фильтру и контексту измерения, предлагать ли измерение резервуару exemplars; вызывают хранилища потоков метрик при записи измерений и сборе наблюдений.

Пример

bsl

// Exemplars для всех измерений, а не только для сэмплированных спанов
Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьРесурс(Ресурс)
    .ЗарегистрироватьЧитатель(Читатель)
    .УстановитьФильтрЭкземпляров(ОтелФильтрЭкземпляров.ВсегдаВключен())
    .Построить();

// Фильтр из настроек приложения в формате OTEL_METRICS_EXEMPLAR_FILTER
Фильтр = ОтелФильтрЭкземпляров.ИзСтроки("always_off"); // ОтелФильтрЭкземпляров.ВсегдаВыключен()
Если Фильтр = Неопределено Тогда
    Фильтр = ОтелФильтрЭкземпляров.ПоТрассировке();
КонецЕсли;
Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьФильтрЭкземпляров(Фильтр)
    .Построить();

См. также

ОтелW3CBaggageПропагатор

Пропагатор Baggage по спецификации W3C Baggage.

Описание

Обеспечивает внедрение и извлечение Baggage в/из HTTP-заголовков по спецификации W3C Baggage.

Используемый заголовок: baggage
Формат: key1=value1,key2=value2;metadata

Значения кодируются percent-encoding по спецификации W3C Baggage. Общий размер заголовка ограничен 8192 байтами: если значение превышает ограничение, заголовок не внедряется и записывается предупреждение в лог.

Использует ОтелГеттерТекстовойКарты и ОтелСеттерТекстовойКарты по умолчанию.

Конструктор

Конструктор без параметров.

bsl

Новый ОтелW3CBaggageПропагатор()

Методы

Внедрить

Внедряет Baggage из контекста в заголовок baggage носителя. Если Baggage отсутствует или пустое — ничего не делает.

Метаданные записи внедряются после ; без пробелов по краям. Метаданные вне грамматики свойств W3C Baggage (например, не US-ASCII) опускаются, сама запись внедряется.

Параметр	Тип	По умолчанию	Описание
`Контекст`	Соответствие	—	OTel Context
`Носитель`	Произвольный	—	Носитель заголовков
`Сеттер`	ОтелСеттерТекстовойКарты	Стандартный сеттер	Объект для записи в носитель

Извлечь

Извлекает Baggage из заголовка baggage носителя в новый контекст. Если заголовок отсутствует или в нем нет ни одной пары ключ=значение — возвращает исходный контекст без изменений, существующий baggage сохраняется. Части без = или с пустым ключом пропускаются.

Параметр	Тип	По умолчанию	Описание
`Контекст`	Соответствие	—	Входной OTel Context
`Носитель`	Произвольный	—	Носитель заголовков
`Геттер`	ОтелГеттерТекстовойКарты	Стандартный геттер	Объект для чтения из носителя

Возвращает: Соответствие — новый контекст с Baggage (или входной контекст, если заголовок отсутствует)

Поля

Возвращает список HTTP-заголовков, используемых пропагатором.

Возвращает: Массив из Строка — ["baggage"]

Пример

bsl

#Использовать opentelemetry

Пропагатор = Новый ОтелW3CBaggageПропагатор();

// Создать контекст с Baggage
Багаж = Новый ОтелПостроительBaggage()
    .Установить("user.id", "42")
    .Установить("tenant", "acme")
    .Построить();
Контекст = ОтелКонтекст.КонтекстСBaggage(ОтелКонтекст.Текущий(), Багаж);

// Внедрить в заголовки
Заголовки = Новый Соответствие();
Пропагатор.Внедрить(Контекст, Заголовки);
// baggage: user.id=42,tenant=acme

// Извлечь из входящих заголовков
ВходящиеЗаголовки = Новый Соответствие();
ВходящиеЗаголовки.Вставить("baggage", "user.id=42,tenant=acme");
НовыйКонтекст = Пропагатор.Извлечь(Новый Соответствие(), ВходящиеЗаголовки);

ОтелW3CПропагатор

Пропагатор контекста трассировки W3C Trace Context.

Описание

Реализует внедрение и извлечение контекста трассировки через HTTP-заголовки traceparent и tracestate согласно спецификации W3C Trace Context Level 2.

Формат traceparent: {version}-{trace-id}-{parent-id}-{trace-flags}
Пример: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Поля trace-flags (1 байт):

Бит 0 (маска 0x01) — sampled
Бит 1 (маска 0x02) — random (W3C Level 2): TraceId сгенерирован случайно

Все биты сохраняются при round-trip через числовое поле ФлагиТрассировки в ОтелКонтекстСпана. Парсинг tracestate выполняется через ОтелСостояниеТрассировки с RFC-валидацией ключей и значений.

Использует ОтелГеттерТекстовойКарты и ОтелСеттерТекстовойКарты по умолчанию.

Конструктор

Конструктор без параметров.

bsl

Новый ОтелW3CПропагатор()

Методы

Внедрить

Внедряет контекст трассировки (SpanContext) в HTTP-заголовки носителя. Если контекст не содержит валидного спана — ничего не делает.

Параметр	Тип	По умолчанию	Описание
`Контекст`	Соответствие	—	OTel Context
`Носитель`	Произвольный	—	Носитель заголовков
`Сеттер`	ОтелСеттерТекстовойКарты	Стандартный сеттер	Объект для записи в носитель

Извлечь

Извлекает SpanContext из HTTP-заголовков носителя в новый OTel Context. При невалидном заголовке возвращает исходный контекст без изменений. Невалидным считается заголовок, в котором версия, trace-id, parent-id или флаги имеют неверную длину или содержат что-то кроме строчных hex-символов (W3C допускает только 0-9a-f), а также заголовок с нулевыми идентификаторами или версией ff.

Параметр	Тип	По умолчанию	Описание
`Контекст`	Соответствие	—	Входной OTel Context
`Носитель`	Произвольный	—	Носитель заголовков
`Геттер`	ОтелГеттерТекстовойКарты	Стандартный геттер	Объект для чтения из носителя

Возвращает: Соответствие — новый контекст с извлечённым SpanContext (или входной контекст при ошибке)

Поля

Возвращает список HTTP-заголовков, используемых пропагатором.

Возвращает: Массив из Строка — ["traceparent", "tracestate"]

Пример

bsl

#Использовать opentelemetry

Пропагатор = Новый ОтелW3CПропагатор();

// Внедрить контекст в исходящий запрос
Заголовки = Новый Соответствие();
Пропагатор.Внедрить(ОтелКонтекст.Текущий(), Заголовки);
// Заголовки теперь содержит traceparent: 00-...

// Извлечь контекст из входящего запроса
ВходящиеЗаголовки = Новый Соответствие();
ВходящиеЗаголовки.Вставить("traceparent", "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
НовыйКонтекст = Пропагатор.Извлечь(Новый Соответствие(), ВходящиеЗаголовки);

// Использовать совместно с композитным пропагатором
Список = Новый Массив();
Список.Добавить(Пропагатор);
Список.Добавить(Новый ОтелW3CBaggageПропагатор());
КомпПропагатор = Новый ОтелКомпозитныйПропагатор(Список);

ОтелГеттерТекстовойКарты

Геттер текстовой карты для пропагаторов.

Описание

Реализует абстракцию Getter для работы с носителем типа Соответствие. Обеспечивает case-insensitive доступ к заголовкам для HTTP-совместимости.

Объект является stateless и может быть сохранён как константа — создавать новый экземпляр для каждой операции не требуется.

Конструктор

Конструктор без параметров. Stateless — без состояния.

bsl

Новый ОтелГеттерТекстовойКарты()

Методы

Получить

Возвращает первое значение по заданному ключу из носителя. Поиск выполняется без учёта регистра для HTTP-совместимости.

Параметр	Тип	По умолчанию	Описание
`Носитель`	Соответствие	—	Коллекция заголовков
`Ключ`	Строка	—	Имя заголовка

Возвращает: Строка, Неопределено — первое найденное значение или Неопределено

ПолучитьВсе

Возвращает все значения по заданному ключу из носителя. Поиск выполняется без учёта регистра.

Параметр	Тип	По умолчанию	Описание
`Носитель`	Соответствие	—	Коллекция заголовков
`Ключ`	Строка	—	Имя заголовка

Возвращает: Массив из Строка — все найденные значения (пустой массив, если ключ не найден)

Ключи

Возвращает список всех ключей из носителя.

Параметр	Тип	По умолчанию	Описание
`Носитель`	Соответствие	—	Коллекция заголовков

Возвращает: Массив из Строка — список ключей

Пример

bsl

#Использовать opentelemetry

Геттер = Новый ОтелГеттерТекстовойКарты();

Заголовки = Новый Соответствие();
Заголовки.Вставить("traceparent", "00-abc123...");
Заголовки.Вставить("Content-Type", "application/json");

// Case-insensitive поиск
Значение = Геттер.Получить(Заголовки, "TRACEPARENT"); // "00-abc123..."
Значение = Геттер.Получить(Заголовки, "content-type"); // "application/json"

// Получить все ключи
Ключи = Геттер.Ключи(Заголовки); // ["traceparent", "Content-Type"]

// Использование с пропагатором
Пропагатор = Новый ОтелW3CПропагатор();
НовыйКонтекст = Пропагатор.Извлечь(ОтелКонтекст.Текущий(), Заголовки, Геттер);

ОтелКомпозитныйПропагатор

Композитный пропагатор (CompositePropagator) по спецификации OpenTelemetry.

Описание

Объединяет несколько пропагаторов в единую цепочку. Позволяет одновременно использовать, например, ОтелW3CПропагатор и ОтелW3CBaggageПропагатор.

Внедрить() — вызывает все пропагаторы последовательно
Извлечь() — цепочечно передаёт контекст через все пропагаторы
Поля() — возвращает объединённый список заголовков всех пропагаторов

Ошибки отдельного пропагатора не прерывают выполнение цепочки: они записываются в лог как предупреждения и обработка продолжается со следующим пропагатором.

Конструктор

bsl

Новый ОтелКомпозитныйПропагатор(Пропагаторы)

Параметр	Тип	По умолчанию	Описание
`Пропагаторы`	Массив	—	Массив объектов-пропагаторов

Методы

Внедрить

Внедряет контекст через все пропагаторы последовательно.

Параметр	Тип	По умолчанию	Описание
`Контекст`	Произвольный	—	Контекст для внедрения (Спан, Baggage и т.д.)
`Носитель`	Произвольный	—	Носитель заголовков
`Сеттер`	ОтелСеттерТекстовойКарты	`Неопределено`	Объект для записи в носитель (по умолчанию для Соответствие)

Извлечь

Извлекает контекст из заголовков через все пропагаторы последовательно. Каждый пропагатор получает контекст, обогащённый предыдущим.

Параметр	Тип	По умолчанию	Описание
`Контекст`	Соответствие	—	Входной OTel Context
`Носитель`	Произвольный	—	Носитель заголовков
`Геттер`	ОтелГеттерТекстовойКарты	`Неопределено`	Объект для чтения из носителя (по умолчанию для Соответствие)

Возвращает: Соответствие — контекст, обогащённый данными от всех пропагаторов

Поля

Возвращает объединённый список заголовков всех пропагаторов.

Возвращает: Массив из Строка — список имён полей заголовков

Пример

bsl

#Использовать opentelemetry

// Объединить W3C TraceContext и Baggage пропагаторы
Список = Новый Массив();
Список.Добавить(Новый ОтелW3CПропагатор());
Список.Добавить(Новый ОтелW3CBaggageПропагатор());

КомпПропагатор = Новый ОтелКомпозитныйПропагатор(Список);

// Внедрить все данные в заголовки
Заголовки = Новый Соответствие();
КомпПропагатор.Внедрить(ОтелКонтекст.Текущий(), Заголовки);
// Заголовки содержит traceparent, tracestate и baggage

// Извлечь все данные из входящих заголовков (здесь — из только что заполненных)
ВходящиеЗаголовки = Заголовки;
НовыйКонтекст = КомпПропагатор.Извлечь(Новый Соответствие(), ВходящиеЗаголовки);

// Получить все используемые поля
Поля = КомпПропагатор.Поля();
// ["traceparent", "tracestate", "baggage"]

ОтелНоопПропагатор

Пустой пропагатор контекста (no-op): ничего не внедряет и не извлекает.

Описание

Методы те же, что у остальных пропагаторов (Внедрить, Извлечь, Поля), но носитель и контекст не меняются. SDK возвращает этот пропагатор, когда пропагация не настроена или отключена:

ОтелГлобальный.ПолучитьПропагаторы() — если пропагаторы не установлены через ОтелГлобальный.УстановитьПропагаторы() и у глобального SDK их нет (SDK не зарегистрирован или собран без пропагаторов). Так выполняется требование спецификации (раздел Propagators API, Global Propagators): API использует no-op пропагаторы, пока они не настроены явно;
ОтелАвтоконфигурация.СоздатьПропагаторы() — если в OTEL_PROPAGATORS есть значение none (остальные значения списка тогда игнорируются с предупреждением в логе). Этот пропагатор получает SDK из ОтелАвтоконфигурация.Инициализировать(), в том числе отключённый (OTEL_SDK_DISABLED=true);
ОтелКонфигурационнаяФабрика.СоздатьПропагаторы() — если в файле конфигурации нет секции propagator, в ней не задано ни одного пропагатора или задан none (none вместе с другими пропагаторами — ошибка: фабрика выбрасывает исключение). Этот пропагатор получает SDK из ОтелКонфигурационнаяФабрика.Создать(), в том числе созданный ОтелАвтоконфигурация.Инициализировать() по файлу из OTEL_CONFIG_FILE; при disabled: true пропагаторы SDK не задаются.

Пропагатор не хранит состояния: экземпляр можно создать и установить самому, например чтобы отключить пропагацию глобально.

Конструктор

bsl

Новый ОтелНоопПропагатор()

Методы

Внедрить

Ничего не делает: носитель не меняется.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`Соответствие`, `ФиксированноеСоответствие`	—	Контекст; не используется
`Носитель`	`Произвольный`	—	Носитель заголовков; не меняется
`Сеттер`	ОтелСеттерТекстовойКарты	`Неопределено`	Не используется

Извлечь

Возвращает переданный контекст без изменений (тот же объект); носитель не читается.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`Соответствие`, `ФиксированноеСоответствие`	—	Входной контекст
`Носитель`	`Произвольный`	—	Носитель заголовков; не читается
`Геттер`	ОтелГеттерТекстовойКарты	`Неопределено`	Не используется

Возвращает: Соответствие, ФиксированноеСоответствие — переданный Контекст

Поля

Возвращает список полей пропагатора — он пуст.

Возвращает: Массив — пустой массив (новый при каждом вызове)

Пример

bsl

#Использовать opentelemetry

// Пропагаторы не настроены ни явно, ни в SDK: глобальный пропагатор - ОтелНоопПропагатор
Пропагаторы = ОтелГлобальный.ПолучитьПропагаторы();

Заголовки = Новый Соответствие();
Пропагаторы.Внедрить(ОтелКонтекст.Текущий(), Заголовки);
// Заголовки пусты, Пропагаторы.Поля() - пустой массив

// Отключить пропагацию глобально, даже если у SDK пропагаторы настроены:
// установленные явно пропагаторы важнее пропагаторов SDK
ОтелГлобальный.УстановитьПропагаторы(Новый ОтелНоопПропагатор());

См. также

ОтелСеттерТекстовойКарты

Сеттер текстовой карты для пропагаторов.

Описание

Реализует абстракцию Setter для работы с носителем типа Соответствие. Сохраняет регистр ключей как есть (согласно спецификации TextMap Propagator: "SHOULD preserve casing"). Нормализацию регистра выполняет транспортный слой.

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

Объект является stateless и может быть сохранён как константа.

Конструктор

Конструктор без параметров.

bsl

Новый ОтелСеттерТекстовойКарты()

Методы

Установить

Устанавливает значение в носителе по ключу. Регистр ключа сохраняется.

Если ключ или значение содержат не US-ASCII символы, запись пропускается и в лог записывается предупреждение (носитель не модифицируется).

Допустимые символы ключа (RFC 9110 token): A-Z, a-z, 0-9, ! # $ % & ' * + - . ^ _ \ | ~ Допустимые символы значения: VCHAR (0x21-0x7E), пробел (0x20), горизонтальный таб (0x09`). Значение не должно начинаться или заканчиваться пробелом или табом.

Параметр	Тип	По умолчанию	Описание
`Носитель`	Соответствие	—	Коллекция заголовков (модифицируется)
`Ключ`	Строка	—	Имя заголовка (US-ASCII)
`Значение`	Строка	—	Значение заголовка (US-ASCII)

Пример

bsl

#Использовать opentelemetry

Сеттер = Новый ОтелСеттерТекстовойКарты();

Заголовки = Новый Соответствие();
Сеттер.Установить(Заголовки, "traceparent", "00-abc123...");
Сеттер.Установить(Заголовки, "tracestate", "vendor=data");

// Невалидный ключ — будет пропущен с предупреждением в лог
Сеттер.Установить(Заголовки, "мой-заголовок", "значение"); // US-ASCII нарушение

// Использование с пропагатором
Пропагатор = Новый ОтелW3CПропагатор();
Пропагатор.Внедрить(ОтелКонтекст.Текущий(), Заголовки, Сеттер);

ИнтерфейсПроцессорСпанов

Интерфейс процессора спанов (SpanProcessor): контракт встроенных и своих процессоров.

Описание

Процессор спанов получает спаны провайдера трассировки: каждый записывающий спан — при начале (ПриНачале) и при завершении (ПриЗавершении). Встроенные процессоры — ОтелПростойПроцессорСпанов, ОтелПакетныйПроцессорСпанов и ОтелКомпозитныйПроцессорСпанов. Свой процессор пишут, например, чтобы дополнять спаны атрибутами или отбирать спаны для экспорта. Аналог Java SDK: SpanProcessor.

Интерфейс — класс ИнтерфейсПроцессорСпанов с аннотацией &Интерфейс библиотеки extends: ПриНачале и ПриЗавершении в нём пустые, СброситьБуфер и Закрыть возвращают успех. Встроенные процессоры объявляют реализацию аннотацией &Реализует("ИнтерфейсПроцессорСпанов") у конструктора ПриСозданииОбъекта.

Регистрация процессора

Процессор добавляют в провайдер трассировки:

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

Провайдер вызывает процессоры в порядке добавления.

Реализацию интерфейса SDK не проверяет: при добавлении не проверяются ни аннотация &Реализует, ни наличие методов — провайдер вызывает методы по имени. Если метода нет, ошибка проявится при вызове: для ПриНачале и ПриЗавершении — предупреждением в логе на каждом спане, для СброситьБуфер и Закрыть — ошибкой в результате провайдера. Проверить класс заранее, например в тестах, можно валидатором библиотеки extends: метод ИнтерфейсыРеализованыКорректно(Процессор) объекта ВалидаторРеализации выбрасывает исключение, если у класса с аннотацией &Реализует("ИнтерфейсПроцессорСпанов") нет метода интерфейса или у метода неподходящее число параметров. Так в тестах библиотеки проверяются встроенные процессоры.

Потоки, исключения и результаты

ПриНачале и ПриЗавершении вызываются синхронно в потоке, который начинает или завершает спан. Спаны могут начинаться и завершаться в нескольких потоках (фоновых заданиях) одновременно, поэтому общие данные процессора защищайте блокировкой. СброситьБуфер и Закрыть вызываются в потоке, который вызвал метод провайдера (у СброситьБуферАсинхронно и ЗакрытьАсинхронно провайдера — в фоновом задании).

Исключение из ПриНачале или ПриЗавершении перехватывает композитный процессор провайдера и пишет в лог предупреждением: спан создаётся и завершается, остальные процессоры вызываются. СброситьБуфер и Закрыть провайдер вызывает у каждого процессора, даже если предыдущий выбросил исключение, и сводит результаты: ошибка, если хотя бы один процессор вернул ошибку или Ложь либо выбросил исключение; иначе таймаут, если процессор вернул таймаут или истёк общий срок; иначе успех. Результат Неопределено (метод-процедура) считается успехом, метод без параметра ТаймаутМс вызывается без срока.

ОтелКомпозитныйПроцессорСпанов вызывает СброситьБуфер строже: с параметром ТаймаутМс и с проверкой Успешно() у результата, поэтому метод без параметра, метод-процедуру или результат Булево он считает ошибкой. Повторяйте сигнатуры интерфейса — тогда процессор работает и в провайдере, и в композитном процессоре.

Методы

ПриНачале

Вызывается при начале спана (OnStart), до того как метод трассировщика или построителя спана вернёт спан. У спана уже заданы имя, вид, начальные атрибуты, линки и время начала. Процессор получает тот же объект спана, что и приложение: ссылку можно сохранить, а спан — изменить, например установить атрибут.

Вызывается только для записывающих спанов: спаны, отброшенные сэмплером, и спаны в API-режиме (SDK не сконфигурирован или трассировщик получен после закрытия провайдера) процессоры не получают. Спаны с решением сэмплера РешениеЗаписать процессоры получают, хотя флаг sampled у них не установлен; экспортер такие спаны получать не должен (спецификация Trace SDK, раздел Sampling), поэтому встроенные процессоры их не экспортируют.

Метод не должен блокировать поток и выбрасывать исключения (спецификация Trace SDK, раздел OnStart): пока он работает, спан не возвращается приложению.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`	—	Начатый спан
`РодительскийКонтекст`	`ФиксированноеСоответствие`	`Неопределено`	Контекст (Context), в котором начат спан: переданный контекст родителя или текущий контекст; у спана из `НачатьКорневойСпан` — текущий контекст, в котором спан заменён невалидным. Из него можно прочитать Baggage — `ОтелКонтекст.BaggageИзКонтекста(РодительскийКонтекст)`

ПриЗавершении

Вызывается при завершении спана (OnEnd) внутри Спан.Завершить(), один раз для каждого спана. Время окончания уже установлено, спан завершён: методы записи игнорируются, данные спана можно только читать.

Метод не должен блокировать поток и выбрасывать исключения (спецификация Trace SDK, раздел OnEnd(Span)): пока он работает, Завершить не возвращает управление. Долгую работу, например отправку спанов, выполняйте в фоне, как пакетный процессор.

Процессор, добавленный в провайдер, пока спан был открыт, получает ПриЗавершении для спана, ПриНачале которого он не получал.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`	—	Завершённый спан

СброситьБуфер

Принудительно завершает обработку спанов, полученных до вызова (ForceFlush): процессор с экспортером экспортирует ещё не отправленные спаны и сбрасывает буфер экспортера. Провайдер вызывает метод из своих СброситьБуфер, ПринудительноВыгрузитьСРезультатом и СброситьБуферАсинхронно; СброситьБуфер провайдера вызывает его и после закрытия провайдера.

Срок: провайдер передаёт время, оставшееся до общего срока операции, а после истечения срока — 1 мс, чтобы процессор завершился без ожидания. Без общего срока метод вызывается без параметра — действует значение по умолчанию из сигнатуры. Соблюдение срока важнее завершения всей работы (спецификация Trace SDK, раздел ForceFlush()): не успев за срок, процессор возвращает таймаут. Результат возвращается, когда выгрузка закончена: результат «в процессе» (с обещанием) провайдер не ожидает и считает ошибкой.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Срок в миллисекундах, `0` — без ограничения

Возвращает: ОтелРезультатЭкспорта — ОтелРезультатыЭкспорта.Успех(), Ошибка() или Таймаут()

Закрыть

Завершает работу процессора (Shutdown). Закрытие включает эффект СброситьБуфер: процессор экспортирует оставшиеся спаны, затем освобождает ресурсы, например закрывает экспортер (спецификация Trace SDK, раздел Shutdown()). Провайдер вызывает метод один раз — при первом Закрыть провайдера (в том числе из ОтелSdk.Закрыть). Срок передаётся так же, как в СброситьБуфер.

После Закрыть процессор ещё может получать ПриНачале и ПриЗавершении — от трассировщиков, полученных до закрытия провайдера, — и СброситьБуфер. Такие вызовы процессору следует игнорировать без исключений (там же).

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Срок в миллисекундах, `0` — без ограничения

Возвращает: ОтелРезультатЗакрытия — ОтелРезультатыЗакрытия.Успех(), Ошибка(Описание) или Таймаут()

Пример

Процессор, который копирует запись Baggage в атрибут спана, — класс приложения в файле ПроцессорBaggage.os:

bsl

Перем КлючBaggage;

Процедура ПриНачале(Спан, РодительскийКонтекст = Неопределено) Экспорт
    Baggage = ОтелКонтекст.BaggageИзКонтекста(РодительскийКонтекст);
    Если Baggage = Неопределено Тогда
        Возврат;
    КонецЕсли;
    Значение = Baggage.Получить(КлючBaggage);
    Если Значение <> Неопределено Тогда
        Спан.УстановитьАтрибут(КлючBaggage, Значение);
    КонецЕсли;
КонецПроцедуры

Процедура ПриЗавершении(Спан) Экспорт
КонецПроцедуры

Функция СброситьБуфер(ТаймаутМс = 0) Экспорт
    Возврат ОтелРезультатыЭкспорта.Успех();
КонецФункции

Функция Закрыть(ТаймаутМс = 0) Экспорт
    Возврат ОтелРезультатыЗакрытия.Успех();
КонецФункции

&Реализует("ИнтерфейсПроцессорСпанов")
Процедура ПриСозданииОбъекта(Ключ)
    КлючBaggage = Ключ;
КонецПроцедуры

Регистрация процессора:

bsl

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "ПроцессорBaggage.os"), "ПроцессорBaggage");

Экспортер = Новый ОтелЭкспортерСпанов(Новый ОтелHttpТранспорт("http://localhost:4318"));

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .ДобавитьПроцессор(Новый ПроцессорBaggage("tenant.id"))
    .ДобавитьПроцессор(Новый ОтелПростойПроцессорСпанов(Экспортер))
    .Построить();

Проверка реализации в тесте:

bsl

#Использовать extends

// opentelemetry и класс ПроцессорBaggage подключены, как в примере выше;
// при ошибке реализации валидатор выбрасывает исключение
Валидатор = Новый ВалидаторРеализации();
Валидатор.ИнтерфейсыРеализованыКорректно(Новый ПроцессорBaggage("tenant.id"));

См. также

ИнтерфейсСэмплер

Интерфейс сэмплера (Sampler): контракт встроенных и своих сэмплеров.

Описание

Сэмплер решает при создании каждого спана, записывается ли спан и экспортируется ли он. Встроенные сэмплеры — AlwaysOn, AlwaysOff, TraceIdRatioBased, ParentBased и AlwaysRecord — создаёт модуль ОтелСэмплер. Свой сэмплер пишут, например, чтобы не записывать служебные запросы по имени спана или сэмплировать операции с разной долей. Аналог Java SDK: Sampler.

Интерфейс — класс ИнтерфейсСэмплер с аннотацией &Интерфейс библиотеки extends. Встроенные сэмплеры объявляют реализацию аннотацией &Реализует("ИнтерфейсСэмплер") у конструктора ПриСозданииОбъекта.

Регистрация сэмплера

Сэмплер задаётся провайдеру трассировки при создании: методом УстановитьСэмплерпостроителя провайдера или параметром конструктора провайдера. Без сэмплера провайдер использует сэмплер по умолчанию ParentBased(root=AlwaysOn). Свой сэмплер можно сделать корневым сэмплером или делегатом ОтелСэмплер.НаОсновеРодителя, обернуть в ОтелСэмплер.ВсегдаЗаписывать и наоборот: сэмплеры комбинируются, как объекты одного интерфейса.

Реализацию интерфейса SDK не проверяет: трассировщик вызывает методы по имени. Проверить класс заранее, например в тестах, можно валидатором библиотеки extends: метод ИнтерфейсыРеализованыКорректно(Сэмплер) объекта ВалидаторРеализации выбрасывает исключение, если у класса с аннотацией &Реализует("ИнтерфейсСэмплер") нет метода интерфейса или у метода неподходящее число параметров.

Потоки

ДолженСэмплировать и Описание вызываются из разных потоков (фоновых заданий) одновременно: спаны создаются параллельно. Сэмплер должен быть потокобезопасным (спецификация Trace SDK, раздел Concurrency requirements): встроенные сэмплеры после создания не изменяются, общие изменяемые данные своего сэмплера защищайте блокировкой.

Методы

ДолженСэмплировать

Принимает решение о сэмплировании создаваемого спана (ShouldSample). Трассировщик вызывает метод при создании каждого спана в SDK-режиме, до вызова процессоров. Порядок по спецификации Trace SDK (раздел SDK Span creation): TraceId родителя или новый TraceId, решение сэмплера, новый SpanId, спан по решению.

Параметр	Тип	Описание
`Контекст`	`ФиксированноеСоответствие`	Контекст (Context) с родительским спаном. Спана нет или его SpanContext невалиден — создаётся корневой спан. Контекст спана родителя возвращает ОтелСэмплер.КонтекстСпанаРодителя; Baggage — `ОтелКонтекст.BaggageИзКонтекста(Контекст)`
`ИдТрассировки`	`Строка`	TraceId создаваемого спана (32 hex-символа). При валидном родителе совпадает с TraceId родителя
`ИмяСпана`	`Строка`	Имя создаваемого спана
`ВидСпана`	`Число`	Вид создаваемого спана, значение ОтелВидСпана; не заданный при создании вид — `Внутренний`
`Атрибуты`	`Соответствие`, `ФиксированноеСоответствие`	Начальные атрибуты создаваемого спана; без атрибутов — пустое соответствие
`Линки`	`Массив`, `ФиксированныйМассив` из ОтелЛинк	Линки создаваемого спана; без линков — пустой массив

Атрибуты и линки сэмплер только читает: это коллекции создаваемого спана.

Возвращает: ОтелРезультатСэмплирования — решение, атрибуты, которые получит спан, и TraceState спана:

решение ОтелСэмплер.РешениеОтбросить() (DROP) — спан не записывается: возвращается незаписывающий спан с новыми TraceId и SpanId, процессоры его не получают;
ОтелСэмплер.РешениеЗаписать() (RECORD_ONLY) — спан записывается и передаётся процессорам, флаг sampled не устанавливается, экспортер спан не получает;
ОтелСэмплер.РешениеЗаписатьИЭкспортировать() (RECORD_AND_SAMPLE) — спан записывается, флаг sampled устанавливается, спан экспортируется.

Атрибуты результата устанавливаются у записывающего спана после начальных (одноименные заменяют их) и видны процессорам уже в ПриНачале. TraceState результата становится TraceState спана: пустой очищает состояние трассировки, а результат без TraceState сохраняет TraceState родителя. Результат без атрибутов и TraceState возвращает ОтелСэмплер.Результат(Решение) — без создания объекта на каждый спан.

Описание

Возвращает имя сэмплера или краткое описание с настройками (GetDescription), например TraceIdRatioBased{0.000100}. Описание предназначено для логов и отладки. Оно может меняться со временем, если сэмплер меняет параметры: не кэшируйте его.

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

Пример

Сэмплер, который не записывает проверки работоспособности, а остальные спаны передаёт другому сэмплеру, — класс приложения в файле СэмплерБезПроверок.os:

bsl

Перем Делегат;

Функция ДолженСэмплировать(Контекст, ИдТрассировки, ИмяСпана, ВидСпана, Атрибуты, Линки) Экспорт
    Если ИмяСпана = "GET /health" Тогда
        Возврат ОтелСэмплер.Результат(ОтелСэмплер.РешениеОтбросить());
    КонецЕсли;
    Возврат Делегат.ДолженСэмплировать(Контекст, ИдТрассировки, ИмяСпана, ВидСпана, Атрибуты, Линки);
КонецФункции

Функция Описание() Экспорт
    Возврат "SkipHealthChecks{" + Делегат.Описание() + "}";
КонецФункции

&Реализует("ИнтерфейсСэмплер")
Процедура ПриСозданииОбъекта(НовыйДелегат)
    Делегат = НовыйДелегат;
КонецПроцедуры

Регистрация сэмплера: корневые спаны без проверок работоспособности сэмплируются с долей 10%, дочерние наследуют решение родителя:

bsl

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "СэмплерБезПроверок.os"), "СэмплерБезПроверок");

Корневой = Новый СэмплерБезПроверок(ОтелСэмплер.ПоДолеТрассировок(0.1));
Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьСэмплер(ОтелСэмплер.НаОсновеРодителя(Корневой))
    .Построить();

Сэмплер, который добавляет атрибут к сэмплированным спанам:

bsl

Функция ДолженСэмплировать(Контекст, ИдТрассировки, ИмяСпана, ВидСпана, Атрибуты, Линки) Экспорт
    Результат = Делегат.ДолженСэмплировать(Контекст, ИдТрассировки, ИмяСпана, ВидСпана, Атрибуты, Линки);
    Если Результат.Решение() = ОтелСэмплер.РешениеОтбросить() Тогда
        Возврат Результат;
    КонецЕсли;
    АтрибутыСэмплера = Новый Соответствие();
    АтрибутыСэмплера.Вставить("sampler.name", Делегат.Описание());
    Возврат Новый ОтелРезультатСэмплирования(Результат.Решение(), АтрибутыСэмплера,
        Результат.СостояниеТрассировки());
КонецФункции

См. также

ОтелВидСпана

Модуль — перечисление видов (типов) спанов.

Описание

Аналог Java SDK: SpanKind. Предоставляет числовые константы для установки вида спана через ОтелПостроительСпана.УстановитьВидСпана().

Функции-константы

Внутренний

Спан представляет внутреннюю операцию внутри сервиса. Значение по умолчанию.

Возвращает: Число

Сервер

Спан охватывает серверную часть синхронного RPC или HTTP-запроса.

Возвращает: Число

Клиент

Спан охватывает клиентскую часть синхронного RPC или HTTP-запроса (исходящий запрос).

Возвращает: Число

Производитель

Спан описывает производителя сообщения в асинхронной системе (очередь, брокер).

Возвращает: Число

Потребитель

Спан описывает потребителя сообщения из асинхронной системы.

Возвращает: Число

Пример

bsl

Спан = Трассировщик.ПостроительСпана("GET /api/users")
    .УстановитьВидСпана(ОтелВидСпана.Сервер())
    .НачатьСпан();

См. также

ОтелКодСтатуса

Модуль — перечисление кодов статуса спана.

Описание

Аналог Java SDK: StatusCode. Предоставляет числовые константы для ОтелСпан.УстановитьСтатус().

По спецификации OpenTelemetry статус не может быть «понижен»: установленный Ок или Ошибка не может быть заменён на НеУстановлен; переход Ок → Ошибка игнорируется.

Функции-константы

НеУстановлен

Статус по умолчанию — операция прошла без явного указания результата.

Возвращает: Число

Ок

Операция завершилась успешно.

Возвращает: Число

Ошибка

Операция завершилась с ошибкой.

Возвращает: Число

Пример

bsl

Попытка
    // ... выполнение операции ...
    Спан.УстановитьСтатус(ОтелКодСтатуса.Ок());
Исключение
    Спан.УстановитьСтатус(
        ОтелКодСтатуса.Ошибка(),
        ОписаниеОшибки()
    );
КонецПопытки;

См. также

ОтелСпан

ОтелКомпозитныйПроцессорСпанов

Композитный процессор спанов: передаёт вызовы цепочке процессоров.

Описание

Объединяет несколько процессоров спанов в один процессор (ИнтерфейсПроцессорСпанов): вызовы передаются процессорам цепочки в порядке их добавления. Нужен, когда группу процессоров надо добавить в провайдер как один процессор, — например, чтобы отправлять спаны в несколько систем.

Провайдер трассировки сам хранит свои процессоры в композитном процессоре, поэтому несколько процессоров можно добавить и без него — вызвав ДобавитьПроцессор построителя или провайдера несколько раз. Файловая конфигурация (ОтелКонфигурационнаяФабрика) объединяет в композитный процессор процессоры спанов, если их несколько.

Безопасен для вызова из нескольких потоков: ДобавитьПроцессор создаёт новый список процессоров, а вызовы обходят список, который был текущим в момент вызова.

Конструктор

bsl

Новый ОтелКомпозитныйПроцессорСпанов(Процессоры)

Параметр	Тип	По умолчанию	Описание
`Процессоры`	`Массив`	—	Процессоры спанов в порядке вызова, может быть пустым. Массив копируется: его изменение после создания цепочку не меняет

Методы

ДобавитьПроцессор

Добавляет процессор в конец цепочки. Обход цепочки, уже начатый в другом потоке или в самом процессоре, продолжается по прежнему списку, новый процессор получает следующие вызовы. Тип процессора не проверяется.

Параметр	Тип	По умолчанию	Описание
`Процессор`	`Произвольный`	—	Процессор спанов: встроенный или свой, реализующий ИнтерфейсПроцессорСпанов

Методы процессора

Методы ИнтерфейсПроцессорСпанов, когда композитный процессор добавлен в провайдер трассировки. ПриНачале и ПриЗавершении вызывает спан при создании и в Завершить() через цепочку процессоров провайдера. СброситьБуфер вызывает провайдер из своих СброситьБуфер и ПринудительноВыгрузитьСРезультатом, Закрыть — из своего Закрыть. Приложению вызывать их не нужно.

ПриНачале

Вызывает ПриНачале у каждого процессора цепочки по порядку, с тем же спаном и контекстом. Исключение процессора пишется в лог предупреждением и не прерывает вызов остальных.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`	—	Начатый спан
`РодительскийКонтекст`	`ФиксированноеСоответствие`	`Неопределено`	Контекст (Context), в котором начат спан

ПриЗавершении

Вызывает ПриЗавершении у каждого процессора цепочки по порядку. Исключение процессора пишется в лог предупреждением и не прерывает вызов остальных.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`	—	Завершённый спан

СброситьБуфер

Вызывает СброситьБуфер(ТаймаутМс) у процессоров цепочки по порядку в пределах общего срока: каждый процессор получает время, оставшееся до срока (без срока — 0). Когда срок истёк, оставшиеся процессоры не вызываются. Исключение процессора пишется в лог предупреждением и считается ошибкой, следующие процессоры вызываются.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Общий срок в миллисекундах (`0` — без ограничения)

Возвращает: ОтелРезультатЭкспорта — таймаут, если срок истёк до вызова очередного процессора; иначе неуспешный результат процессора (если таких несколько — последнего; исключение — ошибка); иначе успех

Закрыть

Вызывает Закрыть у каждого процессора цепочки — даже после исключения в предыдущем и после истечения общего срока: процессор получает время, оставшееся до срока, после истечения срока — 1 мс. Без срока (0) Закрыть процессоров вызывается без параметра. Неуспешный итог пишется в лог предупреждением.

Признака закрытия у композитного процессора нет: повторный вызов снова вызывает Закрыть у каждого процессора. Провайдер вызывает Закрыть процессоров один раз.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Общий срок в миллисекундах (`0` — без ограничения)

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

ЕстьПроцессоры — есть ли в цепочке процессоры; по нему Включен() трассировщика проверяет цепочку провайдера;
Процессоры — копия списка процессоров; по ней провайдер вызывает СброситьБуфер и Закрыть у каждого своего процессора.

Пример

bsl

// ПроцессорGrafana и ПроцессорJaeger — пакетные процессоры со своими экспортерами
// (см. ОтелПакетныйПроцессорСпанов)
Процессоры = Новый Массив();
Процессоры.Добавить(ПроцессорGrafana);
Процессоры.Добавить(ПроцессорJaeger);
Процессор = Новый ОтелКомпозитныйПроцессорСпанов(Процессоры);

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .ДобавитьПроцессор(Процессор)
    .Построить();

// ...

// Закрытие провайдера закрывает оба процессора
Провайдер.Закрыть();

См. также

ОтелКонтекстСпана

Неизменяемый контекст спана (SpanContext).

Описание

Содержит W3C Trace Context данные: trace-id (128 бит), span-id (64 бита), флаги трассировки и состояние трассировки. Может быть получен из Спан.КонтекстСпана() или передан из внешней системы через пропагаторы.

Аналог Java SDK: SpanContext.

Методы

ИдТрассировки

Возвращает идентификатор трассировки.

Возвращает: Строка — 32 hex-символа

ИдСпана

Возвращает идентификатор спана.

Возвращает: Строка — 16 hex-символов

ФлагиТрассировки

Возвращает флаги трассировки (W3C TraceFlags).

Возвращает: Число — бит 0 = sampled flag (1 — семплирован)

СостояниеТрассировки

Возвращает состояние трассировки (W3C TraceState).

Возвращает: ОтелСостояниеТрассировки

Удаленный

Возвращает признак удалённого контекста (получен из заголовков, а не создан локально).

Возвращает: Булево — Истина, если контекст пришёл из внешнего источника

Валиден

Проверяет валидность контекста. Валидный контекст имеет ненулевые trace-id и span-id.

Возвращает: Булево

ИдТрассировкиВДвоичномВиде

Возвращает идентификатор трассировки в бинарном виде.

Возвращает: ДвоичныеДанные — 16 байт

ИдСпанаВДвоичномВиде

Возвращает идентификатор спана в бинарном виде.

Возвращает: ДвоичныеДанные — 8 байт

Пример

bsl

КонтекстСпана = Спан.КонтекстСпана();
Если КонтекстСпана.Валиден() Тогда
    ИдТрассировки = КонтекстСпана.ИдТрассировки(); // "4bf92f3577b34da6a3ce929d0e0e4736"
    ИдСпана = КонтекстСпана.ИдСпана();             // "00f067aa0ba902b7"
    Семплирован = (КонтекстСпана.ФлагиТрассировки() ЭтоНЕ 0);
КонецЕсли;

См. также

ОтелЛимитыСпана

Конфигурация лимитов спана (SpanLimits).

Описание

Определяет максимально допустимые количества атрибутов, событий и линков для спана, а также максимальную длину строковых значений атрибутов. Используется при создании провайдера трассировки.

Аналог Java SDK: SpanLimits.

Методы чтения

МаксАтрибутов / КоличествоАтрибутовЛимит

Возвращает максимальное количество атрибутов в спане.

Возвращает: Число

МаксСобытий / КоличествоСобытийЛимит

Возвращает максимальное количество событий в спане.

Возвращает: Число

МаксЛинков / КоличествоСсылокЛимит

Возвращает максимальное количество линков в спане.

Возвращает: Число

МаксДлинаЗначенияАтрибута

Возвращает максимальную длину строкового значения атрибута. Лимит действует и на строки внутри массивов (рекурсивно), двоичные данные усекаются по числу байт.

МаксГлубинаЗначенияАтрибута

Возвращает максимальную глубину значения атрибута. Глубина верхнего значения — 1, вложенный массив на глубине больше лимита заменяется пустым значением.

Возвращает: Число — по умолчанию 64

МаксАтрибутовНаСобытие

Возвращает максимальное количество атрибутов на событие.

Возвращает: Число

МаксАтрибутовНаЛинк

Возвращает максимальное количество атрибутов на линк.

Возвращает: Число

Методы записи (fluent API)

Все методы-сеттеры возвращают ОтелЛимитыСпана для fluent API.

УстановитьМаксАтрибутов / УстановитьКоличествоАтрибутовЛимит

Параметр	Тип	Описание
`Значение`	`Число`	Максимальное количество атрибутов

УстановитьМаксСобытий / УстановитьКоличествоСобытийЛимит

Параметр	Тип	Описание
`Значение`	`Число`	Максимальное количество событий

УстановитьМаксЛинков / УстановитьКоличествоСсылокЛимит

Параметр	Тип	Описание
`Значение`	`Число`	Максимальное количество линков

УстановитьМаксДлинаЗначенияАтрибута

Параметр	Тип	Описание
`Значение`	`Число`, `Неопределено`	Максимальная длина строкового значения; `Неопределено` — без ограничения, `0` — нулевой лимит

УстановитьМаксГлубинаЗначенияАтрибута

Параметр	Тип	Описание
`Значение`	`Число`	Максимальная глубина значения атрибута (глубина верхнего значения — 1)

УстановитьМаксАтрибутовНаСобытие

Параметр	Тип	Описание
`Значение`	`Число`	Максимальное количество атрибутов на событие

УстановитьМаксАтрибутовНаЛинк

Параметр	Тип	Описание
`Значение`	`Число`	Максимальное количество атрибутов на линк

Пример

bsl

Лимиты = Новый ОтелЛимитыСпана()
    .УстановитьМаксАтрибутов(128)
    .УстановитьМаксСобытий(256)
    .УстановитьМаксЛинков(64)
    .УстановитьМаксДлинаЗначенияАтрибута(1024);

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьЛимитыСпана(Лимиты)
    .Построить();

См. также

ОтелЛинк

Линк (Link) к другому спану.

Описание

Неизменяемый DTO, описывающий связь с другим спаном в той же или другой трассировке. Применяется для моделирования зависимостей между трассировками (например, batch-операции или fan-in сценарии).

Аналог Java SDK: LinkData.

Конструктор

Параметр	Тип	По умолчанию	Описание
`НовыйКонтекстСпана`	`ОтелКонтекстСпана`	—	Контекст спана, на который ссылается линк
`НовыеАтрибуты`	`Соответствие`	`Неопределено`	Атрибуты линка
`НовоеОтброшеноАтрибутов`	`Число`	`0`	Количество отброшенных атрибутов

Методы

КонтекстСпана

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

Возвращает: ОтелКонтекстСпана

Атрибуты

Возвращает атрибуты линка.

Возвращает: ОтелАтрибуты

ОтброшеноАтрибутов

Возвращает количество атрибутов, отброшенных из-за лимита.

Возвращает: Число

Пример

bsl

// Добавить линк к уже завершённому спану из другой трассировки
Спан = Трассировщик.ПостроительСпана("обработка-батча")
    .ДобавитьЛинк(ПредыдущийСпан.КонтекстСпана())
    .ДобавитьЛинк(КонтекстВнешнегоСпана)
    .НачатьСпан();

См. также

ОтелНезаписывающийСпан

Незаписывающий спан (NonRecordingSpan).

Описание

Служебный класс библиотеки. Реализует интерфейс спана, как ОтелСпан, но ничего не записывает и не экспортирует. Такой спан возвращают:

методы трассировщика НачатьСпан, НачатьКорневойСпан, НачатьДочернийСпан и ОтелПостроительСпана.НачатьСпан, если сэмплер отбросил спан или SDK не сконфигурирован;
ОтелСпаны.Обернуть(КонтекстСпана) — обёртка контекста спана, например извлечённого пропагатором из заголовков;
ОтелСпаны.Невалидный() — спан с невалидным контекстом (нулевые ID).

Важно: класс предназначен только для служебного использования и НЕ должен создаваться напрямую через Новый ОтелНезаписывающийСпан(...). Конструктор публичен только потому, что OneScript не поддерживает внутренние классы. Чтобы обернуть контекст спана в спан, используйте ОтелСпаны.Обернуть.

Поведение

КонтекстСпана() возвращает обёрнутый контекст спана.
ЗаписьАктивна() возвращает Ложь.
Остальные методы ничего не делают. Завершать такой спан не нужно.

См. также

ОтелПакетныйПроцессорСпанов

Пакетный (асинхронный) процессор спанов.

Описание

Накапливает завершённые спаны в буфере и экспортирует их пакетами в фоновом потоке. Рекомендуется для производственного использования. Является тонкой обёрткой над ОтелБазовыйПакетныйПроцессор.

Аналог Java SDK: BatchSpanProcessor.

Создание

Параметр	Тип	По умолчанию	Описание
`Экспортер`	`Произвольный`	—	Экспортер спанов
`ИмяСигнала`	`Строка`	—	Имя сигнала для лога: `"traces"`
`МаксРазмерБуфера`	`Число`	`2048`	Максимальный размер очереди
`МаксРазмерПакета`	`Число`	`512`	Максимальный размер пакета; размер больше размера очереди ограничивается размером очереди
`ИнтервалЭкспортаМс`	`Число`	`5000`	Интервал фонового экспорта в миллисекундах
`ТаймаутЭкспортаМс`	`Число`	`30000`	Таймаут экспорта в миллисекундах

Спаны экспортирует фоновое задание: оно запускается с первым спаном и отправляет пакет, как только накопился полный пакет или истёк интервал экспорта. ПриЗавершении не ждёт отправку даже при заполнении пакета. ЗапуститьФоновыйЭкспорт() запускает задание заранее; вызывать его не обязательно.

Спан, пришедший в полную очередь, отбрасывается. При извлечении следующего пакета в лог oscript.lib.opentelemetry.traces пишется предупреждение с числом спанов, отброшенных с прошлого пакета.

Методы

ПриНачале

Вызывается при начале спана. В пакетном процессоре не выполняет действий.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`	—	Начавшийся спан
`РодительскийКонтекст`	`Произвольный`	—	Родительский контекст

ПриЗавершении

Вызывается при завершении спана. Помещает сэмплированный спан в буфер и возвращается, не дожидаясь экспорта.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`	—	Завершённый спан

СброситьБуфер

Принудительно экспортирует все спаны из буфера.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах

Возвращает: ОтелРезультатЭкспорта

Закрыть

Завершает работу процессора: останавливает фоновый экспорт, экспортирует оставшиеся в буфере спаны и закрывает экспортер. Все три шага укладываются в один общий срок; экспортер закрывается и после сбоя или таймаута финального экспорта. Повторный вызов возвращает ошибку «Процессор закрыт».

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут в миллисекундах (0 — без ограничения)

Пример

bsl

Экспортер = Новый ОтелЭкспортерСпанов(Новый ОтелGrpcТранспорт("http://localhost:4317"));

Базовый = Новый ОтелБазовыйПакетныйПроцессор(Экспортер, "traces");
Процессор = Новый ПостроительНаследника(Новый ОтелПакетныйПроцессорСпанов(), Базовый).Построить();
Процессор.ЗапуститьФоновыйЭкспорт();

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .ДобавитьПроцессор(Процессор)
    .Построить();

// При завершении работы приложения
РезЗакрытия = Провайдер.Закрыть(30000);
Если НЕ РезЗакрытия.Успешно() Тогда
    Сообщить("Ошибка закрытия: " + РезЗакрытия.Описание());
КонецЕсли;

См. также

ОтелПостроительПровайдераТрассировки

Построитель провайдера трассировки (SdkTracerProviderBuilder).

Описание

Fluent API для создания ОтелПровайдерТрассировки. Аналог Java SDK: SdkTracerProvider.builder().

Методы

УстановитьРесурс

Устанавливает ресурс.

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелРесурс`	—	Ресурс

Возвращает: ОтелПостроительПровайдераТрассировки — ЭтотОбъект для fluent API

ДобавитьПроцессор

Добавляет процессор спанов. Аналог Java SDK: SdkTracerProviderBuilder.addSpanProcessor(processor).

Параметр	Тип	По умолчанию	Описание
`Процессор`	Процессор спанов	—	Встроенный (простой, пакетный, композитный) или свой процессор, см. ИнтерфейсПроцессорСпанов

Возвращает: ОтелПостроительПровайдераТрассировки — ЭтотОбъект для fluent API

УстановитьСэмплер

Устанавливает сэмплер спанов. Без вызова провайдер использует сэмплер по умолчанию ParentBased(root=AlwaysOn); повторный вызов заменяет сэмплер. Аналог Java SDK: SdkTracerProviderBuilder.setSampler(sampler).

Параметр	Тип	По умолчанию	Описание
`НовыйСэмплер`	`ИнтерфейсСэмплер`	—	Встроенный сэмплер из ОтелСэмплер или свой

Возвращает: ОтелПостроительПровайдераТрассировки — ЭтотОбъект для fluent API

УстановитьЛимитыСпана

Устанавливает лимиты спана. Аналог Java SDK: SdkTracerProviderBuilder.setSpanLimits(spanLimits).

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелЛимитыСпана`	—	Лимиты спана

Возвращает: ОтелПостроительПровайдераТрассировки — ЭтотОбъект для fluent API

УстановитьГенераторИд

Устанавливает генератор идентификаторов. Генератор должен реализовывать методы СгенерироватьИдТрассировки() → Строка (32 hex) и СгенерироватьИдСпана() → Строка (16 hex). Идентификаторы — строчные hex-строки, как их передает W3C traceparent. Некорректный идентификатор (не hex, верхний регистр, неверная длина, одни нули) логируется как ошибка и заменяется идентификатором генератора по умолчанию; создание спана не прерывается.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Произвольный`	—	Объект-генератор идентификаторов

Возвращает: ОтелПостроительПровайдераТрассировки — ЭтотОбъект для fluent API

Построить

Создает экземпляр провайдера трассировки.

Возвращает: ОтелПровайдерТрассировки

Пример

bsl

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Процессор)
    .УстановитьСэмплер(ОтелСэмплер.НаОсновеРодителя(ОтелСэмплер.ПоДолеТрассировок(0.25)))
    .Построить();

См. также

ОтелПостроительСпана

Построитель спана (SpanBuilder).

Описание

Создаётся через Трассировщик.ПостроительСпана(ИмяСпана). Позволяет настроить спан до его начала. По умолчанию устанавливает родителем текущий спан контекста.

Аналог Java SDK: SpanBuilder.

Конструктор

Параметр	Тип	По умолчанию	Описание
`Трассировщик`	`ОтелТрассировщик`	—	Трассировщик
`ИмяСпана`	`Строка`	—	Имя спана

Методы

УстановитьРодителя

Устанавливает родительский контекст (Context). Принимает только полный контекст, не спан и не контекст спана: спан оборачивается в контекст через ОтелКонтекст.КонтекстСоСпаном().

Родитель определяется по контексту: спан из контекста становится родителем, контекст без спана даёт корневой спан (неявный текущий контекст не используется; без SDK — пустой незаписывающий спан). Заданный контекст передаётся процессорам в ПриНачале.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Соответствие`, `ФиксированноеСоответствие`	—	Родительский контекст (Context)

Возвращает: ОтелПостроительСпана — ЭтотОбъект для fluent API

БезРодителя

Явно указывает, что спан должен быть корневым (без родителя). Отменяет УстановитьРодителя.

Возвращает: ОтелПостроительСпана — ЭтотОбъект для fluent API

УстановитьВидСпана

Устанавливает вид спана.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Вид из ОтелВидСпана

Возвращает: ОтелПостроительСпана — ЭтотОбъект для fluent API

УстановитьАтрибут

Добавляет начальный атрибут. Атрибуты, добавленные до НачатьСпан(), передаются сэмплеру.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Имя атрибута
`Значение`	`Строка`, `Число`, `Булево`, `Массив`	—	Значение атрибута

Возвращает: ОтелПостроительСпана — ЭтотОбъект для fluent API

ДобавитьЛинк

Добавляет линк к другому спану. Линк к контексту, известному при создании спана, лучше задавать здесь, а не через ОтелСпан.ДобавитьЛинк после создания: решение сэмплера (head sampling) учитывает только данные, известные при создании спана.

Параметр	Тип	По умолчанию	Описание
`КонтекстСпана`	`ОтелКонтекстСпана`	—	Контекст спана
`НовыеАтрибуты`	`Соответствие`	`Неопределено`	Атрибуты линка

Возвращает: ОтелПостроительСпана — ЭтотОбъект для fluent API

УстановитьВремяНачала

Устанавливает время начала спана. Время передаётся при создании спана: процессоры видят его уже в ПриНачале.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	Время начала в наносекундах (Unix epoch)

Возвращает: ОтелПостроительСпана — ЭтотОбъект для fluent API

НачатьСпан

Создаёт и возвращает настроенный спан. Если семплер решил отбросить спан — возвращает незаписывающий спан (ОтелНезаписывающийСпан — служебный класс, напрямую не создаётся).

Возвращает: ОтелСпан, ОтелНезаписывающийСпан

Пример

bsl

Спан = Трассировщик.ПостроительСпана("обработка")
    .УстановитьВидСпана(ОтелВидСпана.Сервер())
    .УстановитьАтрибут("http.method", "POST")
    .УстановитьАтрибут("http.url", АдресЗапроса)
    .НачатьСпан();

См. также

ОтелПостроительТрассировщика

Построитель трассировщика (TracerBuilder): задаёт параметры области инструментирования и получает трассировщик.

Описание

Создаётся через ПостроительТрассировщика(ИмяБиблиотеки) провайдера трассировки или ОтелSdk (SDK передаёт вызов своему провайдеру трассировки). Имя инструментирующей библиотеки задаётся при создании построителя, версия, адрес схемы и атрибуты области — методами построителя. Аналог Java SDK: TracerProvider.tracerBuilder("name").

Построить() получает трассировщик так же, как ПолучитьТрассировщик(ИмяБиблиотеки, ВерсияБиблиотеки, АтрибутыОбласти, АдресСхемы) провайдера: трассировщик с той же областью — именем, версией, адресом схемы и атрибутами — возвращается из кэша провайдера. Пустое имя библиотеки (или Неопределено) допускается: провайдер пишет предупреждение в лог и использует пустое имя.

Незаданные параметры берутся по умолчанию: версия и адрес схемы — пустая строка, атрибутов области нет.

Методы

УстановитьВерсию

Задаёт версию инструментирующей библиотеки.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	Версия библиотеки

Возвращает: ОтелПостроительТрассировщика — ЭтотОбъект для fluent API

УстановитьАдресСхемы

Задаёт адрес схемы телеметрии (schema URL) области.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	Адрес схемы, например `"https://opentelemetry.io/schemas/1.29.0"`

Возвращает: ОтелПостроительТрассировщика — ЭтотОбъект для fluent API

УстановитьАтрибутыОбласти

Задаёт атрибуты области инструментирования (InstrumentationScope). Атрибуты входят в идентичность области: трассировщики одной библиотеки с разными атрибутами — разные трассировщики.

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелАтрибуты`	—	Атрибуты области

Возвращает: ОтелПостроительТрассировщика — ЭтотОбъект для fluent API

Построить

Возвращает трассировщик с заданными параметрами: из кэша провайдера, если трассировщик с такой областью уже создан, иначе новый. Область хранит копию атрибутов: изменение объекта атрибутов после Построить() трассировщик не меняет.

После закрытия провайдера возвращает отключённый трассировщик: его Включен() возвращает Ложь, а спаны он создаёт незаписывающие.

Возвращает: ОтелТрассировщик

Пример

bsl

АтрибутыОбласти = Новый ОтелАтрибуты();
АтрибутыОбласти.Установить("component", "http-client");

Трассировщик = Провайдер.ПостроительТрассировщика("my-library")
    .УстановитьВерсию("1.2.0")
    .УстановитьАдресСхемы("https://opentelemetry.io/schemas/1.29.0")
    .УстановитьАтрибутыОбласти(АтрибутыОбласти)
    .Построить();

Спан = Трассировщик.НачатьСпан("запрос");
Спан.Завершить();

См. также

ОтелПровайдерТрассировки

Провайдер трассировки SDK (SdkTracerProvider).

Описание

Потокобезопасный объект. Создаёт и кэширует трассировщики (ОтелТрассировщик) по идентичности области: имени и версии библиотеки, адресу схемы и атрибутам. Управляет цепочкой процессоров спанов, ресурсом и сэмплером.

Аналог Java SDK: SdkTracerProvider.

Экземпляр создаётся через ОтелПостроительПровайдераТрассировки.

Методы

ПостроительТрассировщика

Создает построитель трассировщика (TracerBuilder).

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки

Возвращает: ОтелПостроительТрассировщика

ПолучитьТрассировщик

Создает или возвращает трассировщик для указанной библиотеки. Повторный вызов с теми же именем, версией, атрибутами и адресом схемы возвращает тот же трассировщик; если отличается хотя бы один параметр — другой.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки
`АтрибутыОбласти`	`ОтелАтрибуты`	`Неопределено`	Атрибуты InstrumentationScope
`АдресСхемы`	`Строка`	`""`	URL схемы телеметрии

Возвращает: ОтелТрассировщик

ДобавитьПроцессор

Добавляет процессор спанов в цепочку.

Параметр	Тип	По умолчанию	Описание
`Процессор`	Процессор спанов	—	Встроенный (простой, пакетный, композитный) или свой процессор, см. ИнтерфейсПроцессорСпанов

Сэмплер

Возвращает сэмплер провайдера: заданный УстановитьСэмплер построителя или сэмплер по умолчанию ParentBased(root=AlwaysOn). Трассировщики провайдера запрашивают у него решение при создании каждого спана.

Возвращает: ИнтерфейсСэмплер — встроенный сэмплер из ОтелСэмплер или свой; описание сэмплера возвращает его метод Описание()

Ресурс

Возвращает ресурс провайдера.

Возвращает: ОтелРесурс

СброситьБуфер

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (0 — без ограничения)

ПринудительноВыгрузитьСРезультатом

Принудительно отправляет накопленные данные через процессоры так же, как СброситьБуфер, но возвращает ОтелРезультатЗакрытия с описаниями ошибок, а срок по умолчанию — 30 секунд. После Закрыть процессоры не вызываются: возвращается ошибка «Провайдер трассировки закрыт».

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут операции в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЗакрытия — ошибка, если провайдер закрыт или хотя бы один процессор сообщил о сбое или бросил исключение (описания ошибок перечислены через ; ); иначе таймаут, если истёк срок или процессор сообщил о таймауте; иначе успех

СброситьБуферАсинхронно

Запускает СброситьБуфер() — без ограничения срока — в фоновом задании и сразу возвращает обещание библиотеки async.

Возвращает: Обещание — Получить(Таймаут) обещания ждёт окончания выгрузки и возвращает ОтелРезультатЭкспорта; если выгрузка не закончилась за Таймаут миллисекунд, Получить выбрасывает исключение

Закрыть

Завершает работу провайдера. Закрыть вызывается у каждого процессора в пределах общего срока — даже после исключения в предыдущем и после истечения срока (тогда процессор получает 1 мс и завершается без ожидания). Повторный вызов ничего не делает и возвращает успех.

После закрытия ПолучитьТрассировщик возвращает отключённый трассировщик — его Включен() возвращает Ложь, спаны он создаёт незаписывающие, — а ПринудительноВыгрузитьСРезультатом возвращает ошибку.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`30000`	Таймаут операции в миллисекундах

ЗакрытьАсинхронно

Запускает Закрыть() — с таймаутом по умолчанию 30000 мс — в фоновом задании и сразу возвращает обещание библиотеки async.

Возвращает: Обещание — Получить(Таймаут) обещания ждёт закрытия и возвращает ОтелРезультатЗакрытия; если закрытие не закончилось за Таймаут миллисекунд, Получить выбрасывает исключение

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

Процессор — внутренний композитный процессор с цепочкой процессоров: трассировщик передаёт его спанам и проверяет по нему, есть ли процессоры;
ЛимитыСпана — лимиты, которые трассировщик передаёт создаваемым спанам;
Включен — признак SDK-режима провайдера, его читает трассировщик. Ложь — у no-op провайдера, который ОтелГлобальный.ПолучитьПровайдерТрассировки() возвращает, пока не задан глобальный провайдер и нет SDK с провайдером трассировки: трассировщики такого провайдера создают незаписывающие спаны, генератор идентификаторов не вызывается. Закрытие признак не меняет;
УстановитьВключен — переключает SDK-режим: ОтелГлобальный выключает им no-op провайдер;
Закрыт — Истина с начала первого вызова Закрыть; SDK его не вызывает, его используют тесты;
СгенерироватьИдТрассировки, СгенерироватьИдСпана — идентификаторы нового спана от генератора из УстановитьГенераторИд построителя или от генератора по умолчанию; некорректный идентификатор генератора пишется в лог ошибкой и заменяется идентификатором генератора по умолчанию.

Пример

bsl

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Процессор)
    .УстановитьСэмплер(ОтелСэмплер.НаОсновеРодителя(ОтелСэмплер.ПоДолеТрассировок(0.25)))
    .Построить();

Трассировщик = Провайдер.ПолучитьТрассировщик("мой-сервис");

См. также

ОтелПростойПроцессорСпанов

Простой (синхронный) процессор спанов.

Описание

Экспортирует спаны синхронно в момент их завершения. Не буферизует данные — каждый завершённый спан немедленно передаётся экспортеру. Подходит для разработки и тестирования; в продакшне рекомендуется использовать ОтелПакетныйПроцессорСпанов.

Аналог Java SDK: SimpleSpanProcessor.

Конструктор

Параметр	Тип	По умолчанию	Описание
`Экспортер`	`Произвольный`	—	Экспортер спанов (должен реализовывать интерфейс экспортера)

Методы

ПриНачале

Вызывается при начале спана. В простом процессоре не выполняет действий.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`	—	Начавшийся спан
`РодительскийКонтекст`	`Произвольный`	—	Родительский контекст

ПриЗавершении

Вызывается при завершении спана. Синхронно экспортирует спан.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`	—	Завершённый спан

СброситьБуфер

Синхронизирует незавершённые операции экспорта: в пределах таймаута дожидается экспорта, начатого в другом потоке, затем сбрасывает буфер экспортера.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (`0` — без ограничения)

Закрыть

Завершает работу процессора: дожидается текущего экспорта, сбрасывает буфер экспортера (СброситьБуфер) и закрывает экспортер — в пределах общего срока. Экспортер закрывается и после сбоя сброса буфера. Повторный вызов ничего не делает и возвращает успех.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (0 — без ограничения)

Пример

bsl

// OTLP HTTP-экспортер (из подсистемы Экспорт)
Экспортер = Новый ОтелЭкспортерСпанов(Новый ОтелHttpТранспорт("http://localhost:4318"));

Процессор = Новый ОтелПростойПроцессорСпанов(Экспортер);

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .ДобавитьПроцессор(Процессор)
    .Построить();

См. также

ОтелРезультатСэмплирования

Результат сэмплирования (SamplingResult): решение сэмплера, атрибуты и TraceState для нового спана.

Описание

Результат возвращает метод ДолженСэмплировать сэмплера (см. ИнтерфейсСэмплер). Трассировщик получает его при создании каждого спана: по решению спан записывается и экспортируется, только записывается или отбрасывается; атрибуты результата добавляются в записывающий спан, TraceState результата становится TraceState спана.

Результат неизменяем. Встроенные сэмплеры возвращают общие результаты без атрибутов, не меняющие TraceState, — их возвращает ОтелСэмплер.Результат. Свой сэмплер может создать результат с атрибутами или TraceState конструктором.

Конструктор

bsl

Новый ОтелРезультатСэмплирования(Решение, Атрибуты, СостояниеТрассировки)

Параметр	Тип	По умолчанию	Описание
`Решение`	`Число`	—	`ОтелСэмплер.РешениеОтбросить()`, `РешениеЗаписать()` или `РешениеЗаписатьИЭкспортировать()`
`Атрибуты`	`ОтелАтрибуты`, `Соответствие`, `ФиксированноеСоответствие`	`Неопределено`	Атрибуты, которые сэмплер добавляет в спан. Результат хранит их неизменяемую копию: изменение переданного набора после создания результата его не меняет
`СостояниеТрассировки`	`ОтелСостояниеТрассировки`	`Неопределено`	TraceState спана; пустой очищает состояние трассировки. Не задан — спан получает TraceState родителя

Методы

Решение

Возвращает решение сэмплера.

Возвращает: Число — ОтелСэмплер.РешениеОтбросить() (0), ОтелСэмплер.РешениеЗаписать() (1) или ОтелСэмплер.РешениеЗаписатьИЭкспортировать() (2)

Атрибуты

Возвращает атрибуты, которые сэмплер добавляет в спан. Трассировщик устанавливает их после начальных атрибутов спана (одноименные заменяют начальные), до вызова процессоров: атрибуты видны уже в ПриНачале. Отброшенный спан атрибутов не получает.

Возвращает: ФиксированноеСоответствие — неизменяемый набор; пустой, если сэмплер атрибутов не задал

СостояниеТрассировки

Возвращает TraceState, который спан получит через свой SpanContext.

Возвращает: ОтелСостояниеТрассировки, Неопределено — TraceState спана; Неопределено, если сэмплер TraceState не меняет: спан получает TraceState родителя, корневой спан — пустой

Пример

bsl

// Проверить решение сэмплера "10% трассировок" для конкретного trace ID
Сэмплер = ОтелСэмплер.ПоДолеТрассировок(0.1);
Контекст = ОтелКонтекст.Текущий();
Результат = Сэмплер.ДолженСэмплировать(Контекст, "4bf92f3577b34da6a3ce929d0e0e4736", "операция",
    ОтелВидСпана.Внутренний(), Новый Соответствие(), Новый Массив());

Если Результат.Решение() = ОтелСэмплер.РешениеЗаписатьИЭкспортировать() Тогда
    Сообщить("Трассировка попадёт в выборку");
КонецЕсли;

// Результат своего сэмплера: спан записывается, получает атрибут и TraceState вендора
Атрибуты = Новый Соответствие();
Атрибуты.Вставить("sampling.rule", "checkout");
Состояние = Новый ОтелСостояниеТрассировки().Установить("myvendor", "sampled");
Результат = Новый ОтелРезультатСэмплирования(ОтелСэмплер.РешениеЗаписатьИЭкспортировать(), Атрибуты,
    Состояние);

См. также

ОтелСобытиеСпана

Событие (Event) спана.

Описание

Именованное событие с меткой времени и атрибутами, добавляемое к спану. Аналог Java SDK: EventData. Создаётся внутри SDK методом ДобавитьСобытие спана; доступен через Спан.События().

Метка времени — строка с числом наносекунд от начала эпохи Unix, как у спана.

Конструктор

Параметр	Тип	По умолчанию	Описание
`Имя`	`Строка`	—	Имя события
`НовыеАтрибуты`	`ОтелАтрибуты`	`Неопределено`	Атрибуты события
`МеткаВремени`	`Строка`	`Неопределено`	Время события в наносекундах от начала эпохи Unix; по умолчанию текущее время
`МаксАтрибутов`	`Число`, `Неопределено`	`Неопределено`	Максимальное количество атрибутов (`Неопределено` — без ограничения, `0` — атрибуты отбрасываются)

Методы

Имя

Возвращает имя события.

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

Время

Возвращает метку времени события.

Возвращает: Строка — наносекунды от начала эпохи Unix

Атрибуты

Возвращает атрибуты события.

Возвращает: ОтелАтрибуты

КоличествоОтброшенныхАтрибутов

Возвращает количество атрибутов, отброшенных из-за лимита.

Возвращает: Число

ВСоответствиеOtlp

Сериализует событие в соответствие для OTLP-экспорта.

Возвращает: Соответствие — словарь в формате OTLP

Пример

bsl

// Чтение событий спана
Для Каждого Событие Из Спан.События() Цикл
    Сообщить("Событие: " + Событие.Имя() + " @ " + Событие.Время());
КонецЦикла;

См. также

ОтелСостояниеТрассировки

Состояние трассировки (W3C TraceState).

Описание

Хранит пары ключ-значение, передаваемые по W3C TraceContext HTTP-заголовку tracestate. Разбор и проверка следуют W3C Trace Context Level 2:

ключ начинается со строчной латинской буквы или цифры и содержит a-z, 0-9, _, -, *, /, @ (например, vendorname или tenant@vendorname), не длиннее 256 символов;
значение — печатные ASCII без , и =, не длиннее 256 символов; ведущие пробелы сохраняются, завершающий пробел недопустим;
не больше 32 записей; состояние длиннее 512 символов усекается целыми записями — сначала удаляются записи длиннее 128 символов, затем записи с конца.

Несколько заголовков tracestate пропагатор объединяет в один через запятую.

Аналог Java SDK: TraceState. Иммутабельный: методы Установить, Удалить возвращают новый экземпляр.

Методы

Получить

Возвращает значение по ключу.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ записи

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

Установить

Добавляет или обновляет значение по ключу. Возвращает новый экземпляр (иммутабельность). Добавленная или обновлённая запись ставится первой; если записей уже 32, новая запись вытесняет крайнюю правую (W3C Trace Context). Невалидные ключ или значение игнорируются с предупреждением, тогда возвращается текущий экземпляр.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ записи
`Значение`	`Строка`	—	Значение записи

Возвращает: ОтелСостояниеТрассировки — новый экземпляр с добавленной записью

Удалить

Удаляет запись по ключу. Возвращает новый экземпляр.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ для удаления

Возвращает: ОтелСостояниеТрассировки — новый экземпляр без удалённой записи

Количество

Возвращает количество записей.

Возвращает: Число

Пустой

Проверяет, что в состоянии нет записей.

Возвращает: Булево — Истина, если записей нет

ВСтроку

Возвращает состояние в формате W3C-заголовка tracestate: записи ключ=значение через запятую без пробелов, в порядке списка — запись, добавленная или обновлённая через Установить, стоит первой. Эту строку W3C-пропагатор передаёт в заголовке tracestate, а экспортер спанов — в поле traceState OTLP.

Возвращает: Строка — например "congo=t61rcWkgMzE,rojo=00f067aa0ba902b7"; пустая строка, если записей нет

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

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

ИнициализироватьИзМассива — заполняет новый экземпляр готовым списком записей (список длиннее 512 символов усекается целыми записями): так Установить и Удалить создают новое состояние.

Пример

bsl

СостояниеТрассировки = Спан.КонтекстСпана().СостояниеТрассировки();
НовоеСостояние = СостояниеТрассировки
    .Установить("vendor1", "value1")
    .Установить("vendor2", "value2");

Сообщить("Записей: " + НовоеСостояние.Количество());
Сообщить(НовоеСостояние.ВСтроку()); // начинается с "vendor2=value2,vendor1=value1"

См. также

ОтелКонтекстСпана

ОтелСпан

Спан трассировки (Span).

Описание

Потокобезопасный объект, содержащий данные одной единицы работы. Создаётся через Трассировщик.НачатьСпан(), НачатьКорневойСпан(), НачатьДочернийСпан() или ОтелПостроительСпана.НачатьСпан().

Важно: Конструктор технически публичен из-за ограничений OneScript, но НЕ должен вызываться напрямую. Используйте только методы трассировщика.

Все методы записи (установка статуса, атрибутов и т.д.) не производят действий, если спан уже завершён.

Время спана и его событий — строка с числом наносекунд от начала эпохи Unix, как в OTLP, например "1700000000500000000". Время, которое SDK ставит само, имеет точность до миллисекунд. Строку для своего времени дают функции ОтелУтилиты.

Методы чтения

Имя

Возвращает имя спана.

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

КонтекстСпана

Возвращает неизменяемый контекст спана (SpanContext).

Возвращает: ОтелКонтекстСпана

ИдРодительскогоСпана

Возвращает идентификатор родительского спана.

Возвращает: Строка — 16 hex-символов или пустая строка для корневого спана

КонтекстРодительскогоСпана

Возвращает контекст спана родителя.

Возвращает: ОтелКонтекстСпана

ВидСпана

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

Возвращает: Число — константа из ОтелВидСпана

ВремяНачала

Возвращает время начала спана.

Возвращает: Строка — наносекунды от начала эпохи Unix

ВремяОкончания

Возвращает время окончания спана.

Возвращает: Строка — наносекунды от начала эпохи Unix; у незавершённого спана — пустая строка

Атрибуты

Возвращает копию атрибутов спана. Изменение копии не меняет спан: атрибуты записываются только через УстановитьАтрибут, который применяет лимиты ОтелЛимитыСпана.

Возвращает: ОтелАтрибуты

События

Возвращает копию списка событий спана: изменение копии спан не меняет.

Возвращает: Массив из ОтелСобытиеСпана

Линки

Возвращает копию списка линков спана: изменение копии спан не меняет.

Возвращает: Массив из ОтелЛинк

Ресурс

Возвращает ресурс спана (из провайдера трассировки).

Возвращает: ОтелРесурс

ОбластьИнструментирования

Возвращает область инструментирования (InstrumentationScope).

Возвращает: ОтелОбластьИнструментирования

БиблиотекаИнструментирования

Устаревший синоним ОбластьИнструментирования (прежнее имя в спецификации — InstrumentationLibrary). Используйте ОбластьИнструментирования.

Возвращает: ОтелОбластьИнструментирования

КодСтатуса

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

Возвращает: Число — константа из ОтелКодСтатуса

СообщениеСтатуса

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

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

Завершен

Проверяет, завершён ли спан.

Возвращает: Булево

ЗаписьАктивна

Проверяет, записывает ли спан данные (IsRecording): Истина до вызова Завершить, Ложь после. У незаписывающего спана (ОтелНезаписывающийСпан) всегда Ложь.

Возвращает: Булево

КоличествоОтброшенныхАтрибутов

Возвращает: Число — количество атрибутов, отброшенных из-за лимита

КоличествоОтброшенныхСобытий

Возвращает: Число — количество событий, отброшенных из-за лимита

КоличествоОтброшенныхЛинков

Возвращает: Число — количество линков, отброшенных из-за лимита

Методы записи

УстановитьАтрибут

Устанавливает атрибут спана; атрибут с тем же ключом перезаписывается. Значение ограничивается лимитами длины и глубины, новый ключ сверх лимита количества атрибутов отбрасывается (ОтелЛимитыСпана). Отброшенные атрибуты считает КоличествоОтброшенныхАтрибутов, о них один раз на спан пишется предупреждение в лог.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Имя атрибута
`Значение`	`Произвольный`	—	Значение атрибута, допустимые типы — см. ОтелАтрибуты

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

ДобавитьСобытие

Добавляет событие спана (ОтелСобытиеСпана). Событие сверх лимита количества событий отбрасывается, у атрибутов события действуют лимиты количества, длины и глубины значений (ОтелЛимитыСпана).

Параметр	Тип	По умолчанию	Описание
`НовоеИмя`	`Строка`	—	Имя события
`НовыеАтрибуты`	`ОтелАтрибуты`	`Неопределено`	Атрибуты события
`МеткаВремени`	`Строка`	`Неопределено`	Время события в наносекундах от начала эпохи Unix, если событие уже произошло; по умолчанию текущее время

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

ЗаписатьИсключение

Записывает исключение событием exception с атрибутами:

exception.message — описание ошибки;
exception.type — машинный код ошибки библиотеки errors (ДиагностикаОшибок.КодОшибки, в том числе через обертки ФабрикаОшибок.Обернуть и ФабрикаОшибок.ОбернутьКонтекстом). У нативной ошибки OneScript без кода тип определяет классификатор native-errors: numeric.division_by_zero, json.reader.not_open, network.connection.refused и т.п.; если нативная ошибка обернута ошибкой без кода, берется код причины. У нераспознанной ошибки без кода атрибут не заполняется: по семантическим соглашениям он обязателен, только если нет exception.message. Тип, переданный в ДополнительныеАтрибуты, главнее кода, и тогда ошибка не классифицируется — классификация стоит порядка 1–2 мс;
exception.stacktrace — описание ошибки и стек вызовов OneScript, включая цепочку причин (Caused by:), в том же формате, что у записи лога (ОтелУтилиты.СтекВызововИсключения).

Статус спана метод не меняет: ошибку отмечает УстановитьСтатус.

Параметр	Тип	По умолчанию	Описание
`ИнформацияОбОшибке`	`ИнформацияОбОшибке`	—	Информация об исключении, обычно `ИнформацияОбОшибке()` в блоке `Исключение`
`ДополнительныеАтрибуты`	`ОтелАтрибуты`	`Неопределено`	Дополнительные атрибуты события; одноимённые заменяют атрибуты `exception.*`

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

УстановитьСтатус

Устанавливает статус спана. По спецификации OpenTelemetry: статус Ок и Ошибка не могут быть понижены до НеУстановлен. Переход Ок → Ошибка игнорируется.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Число`	—	Код статуса из ОтелКодСтатуса
`Сообщение`	`Строка`	`""`	Сообщение статуса (только для `Ошибка`)

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

ДобавитьЛинк

Добавляет линк к другому спану. Линк к контексту, известному при создании спана, лучше задать при создании через ДобавитьЛинк построителя спана: решение сэмплера (head sampling) учитывает только данные, известные при создании спана, и линк, добавленный позже, на него не влияет.

Параметр	Тип	По умолчанию	Описание
`НовыйКонтекстСпана`	`ОтелКонтекстСпана`	—	Контекст связанного спана
`НовыеАтрибуты`	`ОтелАтрибуты`	`Неопределено`	Атрибуты линка

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

ИзменитьИмя

Изменяет имя спана (UpdateName). Сэмплер принимал решение по имени, заданному при создании спана, и после переименования его не пересматривает.

Параметр	Тип	По умолчанию	Описание
`НовоеИмя`	`Строка`	—	Новое имя спана

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

ПереопределитьВремяНачала

Изменяет время начала спана. Время начала лучше задать при создании спана (ВремяНачалатрассировщика или УстановитьВремяНачала построителя спана): тогда процессоры видят его уже в ПриНачале.

Параметр	Тип	По умолчанию	Описание
`НовоеВремяНачала`	`Строка`	—	Время начала в наносекундах от начала эпохи Unix

СделатьТекущим

Помещает спан в текущий контекст (аналог Java Span.makeCurrent()).

Возвращает: ОтелТокенКонтекста — токен для последующего Закрыть()

Завершить

Завершает спан и отправляет его в цепочку процессоров. После вызова методы записи игнорируются, повторный вызов ничего не делает.

Параметр	Тип	По умолчанию	Описание
`НовоеВремяОкончания`	`Строка`	`Неопределено`	Время окончания в наносекундах от начала эпохи Unix; по умолчанию текущее время

Пример

bsl

Спан = Трассировщик.НачатьСпан("SQL-запрос");
Токен = Спан.СделатьТекущим();
Попытка
    Спан.УстановитьАтрибут("db.system.name", "postgresql");
    // ... выполнение запроса ...
    Спан.ДобавитьСобытие("Запрос выполнен");
    Спан.УстановитьСтатус(ОтелКодСтатуса.Ок());
Исключение
    Спан.ЗаписатьИсключение(ИнформацияОбОшибке());
    Спан.УстановитьСтатус(ОтелКодСтатуса.Ошибка(), ОписаниеОшибки());
КонецПопытки;
Токен.Закрыть();
Спан.Завершить();

Время окончания операции, которая уже прошла:

bsl

Окончание = ТекущаяУниверсальнаяДатаВМиллисекундах();
// ...
Спан.Завершить(ОтелУтилиты.МиллисекундыВНаносекунды(Окончание));

См. также

ОтелСпаны

Модуль функций, которые возвращают незаписывающий спан: обёртку контекста спана и невалидный спан.

Описание

Реализует операцию Trace API «обернуть контекст спана в спан» (спецификация, раздел Wrapping a SpanContext in a Span). Аналоги Java: Span.wrap(SpanContext) и Span.getInvalid().

Функции возвращают ОтелНезаписывающийСпан — служебный класс, который не создают через Новый. Такой спан ничего не записывает: ЗаписьАктивна() возвращает Ложь, КонтекстСпана() — обёрнутый контекст, СделатьТекущим() делает спан текущим, методы записи (атрибуты, события, статус и т.д.) ничего не делают. Завершать его не нужно.

Обёртка нужна, когда известен только контекст спана — идентификаторы трассировки и спана, — а API принимает спан. Например, чтобы контекст из другого процесса стал родителем нового спана, его оборачивают в спан, кладут в контекст (Context) через ОтелКонтекст.КонтекстСоСпаном и передают в НачатьДочернийСпан трассировщика. Так же поступает W3C-пропагатор с контекстом спана из заголовка traceparent.

Функции

Обернуть

Оборачивает контекст спана в незаписывающий спан. Для валидного контекста каждый вызов создаёт новый спан с этим контекстом. Без контекста или для невалидного контекста (нулевые идентификаторы) возвращает Невалидный().

Параметр	Тип	По умолчанию	Описание
`КонтекстСпана`	`ОтелКонтекстСпана`	`Неопределено`	Контекст спана

Возвращает: ОтелНезаписывающийСпан — спан с переданным контекстом или невалидный спан

Невалидный

Возвращает незаписывающий спан с невалидным контекстом: идентификаторы трассировки и спана из нулей, флаги 0, пустое состояние трассировки. Объект создаётся при первом вызове и затем переиспользуется.

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

Возвращает: ОтелНезаписывающийСпан

Пример

bsl

// Идентификаторы родительского спана пришли из другого процесса, например в сообщении очереди:
// флаги 1 - спан сэмплирован, Истина - удалённый контекст
КонтекстСпана = Новый ОтелКонтекстСпана(ИдТрассировки, ИдСпана, 1, , Истина);

// Незаписывающий спан с этим контекстом становится родителем нового спана
Родитель = ОтелСпаны.Обернуть(КонтекстСпана);
КонтекстРодителя = ОтелКонтекст.КонтекстСоСпаном(ОтелКонтекст.Текущий(), Родитель);
Спан = Трассировщик.НачатьДочернийСпан("обработка-сообщения", КонтекстРодителя, ОтелВидСпана.Потребитель());
// ...
Спан.Завершить();

// Заглушка вместо спана: методы записи невалидного спана ничего не делают
ФоновыйСпан = ОтелСпаны.Невалидный();
Если ТрассироватьФоновыеЗадачи Тогда
    ФоновыйСпан = Трассировщик.НачатьСпан("фоновая-задача");
КонецЕсли;
// ...
ФоновыйСпан.Завершить();

См. также

ОтелСэмплер

Модуль — встроенные сэмплеры и решения сэмплера.

Описание

Сэмплер решает при создании каждого спана, записывается ли спан и экспортируется ли он (раздел Sampling спецификации Trace SDK). Модуль создаёт встроенные сэмплеры — AlwaysOn, AlwaysOff, TraceIdRatioBased, ParentBased и AlwaysRecord — и содержит константы решений. Сэмплер — объект с методами ИнтерфейсСэмплер: ДолженСэмплировать (ShouldSample) и Описание (GetDescription). Свой сэмплер реализует тот же интерфейс.

Сэмплер задаётся провайдеру трассировки при создании: методом УстановитьСэмплерпостроителя провайдера, параметром конструктора провайдера, переменными окружения OTEL_TRACES_SAMPLER и OTEL_TRACES_SAMPLER_ARG (автоконфигурация) или секцией tracer_provider.sampler файла конфигурации. Сэмплер по умолчанию — ParentBased(root=AlwaysOn): корневые спаны сэмплируются все, дочерние наследуют решение родителя.

Сэмплеры комбинируются: НаОсновеРодителя и ВсегдаЗаписывать принимают другие сэмплеры, встроенные или свои. Встроенные сэмплеры после создания не изменяются и безопасны при вызове из нескольких потоков.

Аналог Java SDK: Sampler и его статические фабрики (Sampler.alwaysOn(), Sampler.traceIdRatioBased(ratio), Sampler.parentBasedBuilder(root)).

Встроенные сэмплеры

ВсегдаВключен

Возвращает сэмплер AlwaysOn: решение РешениеЗаписатьИЭкспортировать для любого спана. Функция возвращает один и тот же объект.

Возвращает: ОтелСэмплерВсегдаВключен — сэмплер с описанием AlwaysOnSampler

ВсегдаВыключен

Возвращает сэмплер AlwaysOff: решение РешениеОтбросить для любого спана. Функция возвращает один и тот же объект.

Возвращает: ОтелСэмплерВсегдаВыключен — сэмплер с описанием AlwaysOffSampler

ПоДолеТрассировок

Создаёт сэмплер TraceIdRatioBased: сэмплирует заданную долю трассировок по их TraceId. Решение — детерминированная функция TraceId: значение случайности R — правые 7 байт TraceId (случайные по W3C Trace Context Level 2), трассировка сэмплируется, если R >= (1 - Доля) * 2^56. Поэтому все спаны трассировки получают одно решение, а сэмплер с большей долей сэмплирует все трассировки сэмплера с меньшей. Флаг sampled родителя сэмплер не учитывает: чтобы дочерние спаны наследовали решение родителя, используйте сэмплер корневым в НаОсновеРодителя.

Параметр	Тип	По умолчанию	Описание
`Доля`	`Число`	—	Доля трассировок для сэмплирования, от 0.0 до 1.0; `1.0` и больше — все трассировки, `0` и меньше — ни одной

Возвращает: ОтелСэмплерПоДолеТрассировок — сэмплер с описанием TraceIdRatioBased{ДОЛЯ}. Доля выводится с шестью знаками после точки (TraceIdRatioBased{0.250000}), а если у неё больше значащих знаков — со всеми (TraceIdRatioBased{0.1234561}): сэмплеры с разными долями различаются по описанию

НаОсновеРодителя

Создаёт сэмплер ParentBased: решение для корневого спана принимает корневой сэмплер, для дочернего — делегат, выбранный по родителю.

Родитель	Удалённый (`Удаленный()`)	Сэмплирован (флаг sampled)	Решает
нет	—	—	`Корневой`
есть	да	да	`УдаленныйРодительСэмплирован`
есть	да	нет	`УдаленныйРодительНеСэмплирован`
есть	нет	да	`ЛокальныйРодительСэмплирован`
есть	нет	нет	`ЛокальныйРодительНеСэмплирован`

Родитель с невалидным SpanContext (например, ОтелСпаны.Невалидный) считается отсутствующим. Удалённый родитель — контекст, извлечённый пропагатором из входящего запроса.

Параметр	Тип	По умолчанию	Описание
`Корневой`	`ИнтерфейсСэмплер`	—	Сэмплер корневых спанов (root)
`УдаленныйРодительСэмплирован`	`ИнтерфейсСэмплер`	`ВсегдаВключен()`	Удалённый родитель сэмплирован (remoteParentSampled)
`УдаленныйРодительНеСэмплирован`	`ИнтерфейсСэмплер`	`ВсегдаВыключен()`	Удалённый родитель не сэмплирован (remoteParentNotSampled)
`ЛокальныйРодительСэмплирован`	`ИнтерфейсСэмплер`	`ВсегдаВключен()`	Локальный родитель сэмплирован (localParentSampled)
`ЛокальныйРодительНеСэмплирован`	`ИнтерфейсСэмплер`	`ВсегдаВыключен()`	Локальный родитель не сэмплирован (localParentNotSampled)

Возвращает: ОтелСэмплерНаОсновеРодителя — сэмплер с описанием ParentBased{root:...,remoteParentSampled:...,remoteParentNotSampled:...,localParentSampled:...,localParentNotSampled:...} из описаний корневого сэмплера и делегатов

ВсегдаЗаписывать

Создаёт сэмплер AlwaysRecord: решение обёрнутого сэмплера РешениеОтбросить заменяется на РешениеЗаписать, решения РешениеЗаписать и РешениеЗаписатьИЭкспортировать, атрибуты и TraceState обёрнутого сэмплера не меняются. Процессоры получают все спаны — например, чтобы считать метрики по всем спанам, — а экспортер получает только спаны, сэмплированные обёрнутым сэмплером.

Параметр	Тип	По умолчанию	Описание
`Корневой`	`ИнтерфейсСэмплер`	—	Обёрнутый сэмплер (root)

Возвращает: ОтелСэмплерВсегдаЗаписывать — сэмплер с описанием AlwaysRecord{ОПИСАНИЕ_ОБЁРНУТОГО}

Решения сэмплера

РешениеЗаписатьИЭкспортировать

Решение RECORD_AND_SAMPLE: спан записывается, флаг sampled устанавливается, спан экспортируется.

Возвращает: Число — 2

РешениеЗаписать

Решение RECORD_ONLY: спан записывается и передаётся процессорам, но флаг sampled не устанавливается и экспортер спан не получает.

Возвращает: Число — 1

РешениеОтбросить

Решение DROP: спан не записывается, возвращается незаписывающий спан.

Возвращает: Число — 0

Служебные функции

Результат

Возвращает результат сэмплирования с решением, без атрибутов и не меняющий TraceState: спан получает TraceState родителя. Результаты трёх решений создаются один раз, поэтому сэмплер может возвращать их, не создавая объект на каждый спан. Встроенные сэмплеры возвращают эти результаты.

Параметр	Тип	По умолчанию	Описание
`Решение`	`Число`	—	`РешениеОтбросить()`, `РешениеЗаписать()` или `РешениеЗаписатьИЭкспортировать()`

Возвращает: ОтелРезультатСэмплирования — неизменяемый результат

КонтекстСпанаРодителя

Возвращает SpanContext родителя создаваемого спана из контекста, который получает сэмплер в ДолженСэмплировать.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`	—	Контекст (Context), переданный сэмплеру

Возвращает: ОтелКонтекстСпана, Неопределено — контекст спана родителя; Неопределено, если спан корневой: в контексте нет спана или его SpanContext невалиден

Пример

bsl

// Сэмплировать 10% новых трассировок, дочерние спаны наследуют решение родителя
Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьСэмплер(ОтелСэмплер.НаОсновеРодителя(ОтелСэмплер.ПоДолеТрассировок(0.1)))
    .Построить();

// Решение удалённого родителя (входящего запроса) не учитывать: к таким трассировкам тоже
// применять долю 10%
ПоДоле = ОтелСэмплер.ПоДолеТрассировок(0.1);
Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьСэмплер(ОтелСэмплер.НаОсновеРодителя(ПоДоле, ПоДоле, ПоДоле))
    .Построить();

// Процессоры получают все спаны, экспортируется 10% трассировок
Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьСэмплер(ОтелСэмплер.ВсегдаЗаписывать(ОтелСэмплер.НаОсновеРодителя(ПоДоле)))
    .Построить();

Сообщить(Провайдер.Сэмплер().Описание());
// AlwaysRecord{ParentBased{root:TraceIdRatioBased{0.100000},remoteParentSampled:AlwaysOnSampler,...}}

См. также

ОтелТрассировщик

Трассировщик — потокобезопасный объект для создания и управления спанами.

Описание

Все публичные методы безопасны для параллельного вызова из нескольких потоков. Создаётся через ОтелПровайдерТрассировки.ПолучитьТрассировщик() или ОтелSdk.ПолучитьТрассировщик(). Аналог Java SDK: Tracer.

Методы

ПостроительСпана

Создает построитель спана (SpanBuilder).

Параметр	Тип	По умолчанию	Описание
`ИмяСпана`	`Строка`	—	Имя спана

Возвращает: ОтелПостроительСпана

Включен

Проверяет, включён ли трассировщик. Возвращает Ложь, если у провайдера нет зарегистрированных процессоров спанов, а также в API-режиме (SDK не сконфигурирован или провайдер закрыт).

Режим создания спанов от результата не зависит:

SDK-режим: IdGenerator + Sampler работают штатно, создаются реальные спаны — в том числе без процессоров.
API-режим: возвращается non-recording Span, IdGenerator не вызывается.

По спецификации: инструментирующий код SHOULD вызывать Включен() непосредственно перед каждым созданием спана, не кэшируя результат надолго.

Возвращает: Булево — Истина, если трассировщик может обрабатывать спаны

НачатьСпан

Начинает новый спан. Если в контексте есть текущий спан с валидным контекстом, создаёт дочерний; иначе — корневой с новым TraceId. Невалидный спан в контексте (нулевые ID, например ОтелСпаны.Невалидный()) родителем не считается.

Параметр	Тип	По умолчанию	Описание
`ИмяСпана`	`Строка`	—	Имя спана
`ВидСпана`	`Число`	`Неопределено`	Вид спана из ОтелВидСпана
`НачальныеАтрибуты`	`Соответствие`	`Неопределено`	Начальные атрибуты, передаются сэмплеру
`Линки`	`Массив из ОтелЛинк`	`Неопределено`	Начальные линки
`ВремяНачала`	`Строка`	`Неопределено`	Время начала в наносекундах (Unix epoch), процессоры видят его уже в `ПриНачале`; по умолчанию текущее время

Возвращает: ОтелСпан, ОтелНезаписывающийСпан — спан или незаписывающий спан, если отброшен семплером. ОтелНезаписывающийСпан — служебный класс, напрямую не создаётся

НачатьКорневойСпан

Начинает новый корневой спан (без родителя). Текущий спан родителем не становится: сэмплер и процессоры (в ПриНачале) получают текущий контекст, в котором спан заменён невалидным, — остальные значения контекста, например Baggage, сохраняются.

Параметр	Тип	По умолчанию	Описание
`ИмяСпана`	`Строка`	—	Имя спана
`ВидСпана`	`Число`	`Неопределено`	Вид спана из ОтелВидСпана
`НачальныеАтрибуты`	`Соответствие`	`Неопределено`	Начальные атрибуты
`Линки`	`Массив из ОтелЛинк`	`Неопределено`	Начальные линки
`ВремяНачала`	`Строка`	`Неопределено`	Время начала в наносекундах; по умолчанию текущее время

Возвращает: ОтелСпан, ОтелНезаписывающийСпан

НачатьДочернийСпан

Начинает новый спан с родителем из переданного контекста (Context): спан из контекста становится родителем, контекст без спана даёт корневой спан. Спан передаётся в контексте через ОтелКонтекст.КонтекстСоСпаном; если известен только контекст спана, его оборачивают в спан функцией ОтелСпаны.Обернуть. Если спан в контексте невалиден (нулевые ID), создаётся корневой спан с новым TraceId. Контекст передаётся процессорам в ПриНачале.

Параметр	Тип	По умолчанию	Описание
`ИмяСпана`	`Строка`	—	Имя спана
`РодительскийКонтекст`	`ФиксированноеСоответствие`, `Соответствие`	—	Контекст (Context) родителя
`ВидСпана`	`Число`	`Неопределено`	Вид спана из ОтелВидСпана
`НачальныеАтрибуты`	`Соответствие`	`Неопределено`	Начальные атрибуты
`Линки`	`Массив из ОтелЛинк`	`Неопределено`	Начальные линки
`ВремяНачала`	`Строка`	`Неопределено`	Время начала в наносекундах; по умолчанию текущее время

Возвращает: ОтелСпан, ОтелНезаписывающийСпан

ОбластьИнструментирования

Возвращает область инструментирования трассировщика.

Возвращает: ОтелОбластьИнструментирования

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

НачатьСпанВКонтексте — начинает спан с родителем из переданного контекста (Context): общая реализация НачатьСпан, НачатьДочернийСпан и НачатьСпан построителя спана с заданным родителем. Приложение вызывает НачатьДочернийСпан — параметры и поведение у него те же.

Пример

bsl

Трассировщик = Сдк.ПолучитьТрассировщик("мой-сервис", "1.0.0");

Спан = Трассировщик.ПостроительСпана("обработка-запроса")
    .УстановитьВидСпана(ОтелВидСпана.Сервер())
    .УстановитьАтрибут("http.method", "GET")
    .НачатьСпан();

Токен = Спан.СделатьТекущим();
Попытка
    // ... логика обработки ...
Исключение
    Спан.ЗаписатьИсключение(ИнформацияОбОшибке());
    Спан.УстановитьСтатус(ОтелКодСтатуса.Ошибка());
КонецПопытки;
Токен.Закрыть();
Спан.Завершить();

См. также

ИнтерфейсЭкспортерЛогов

Интерфейс экспортера записей лога (LogRecordExporter) — методы, которые процессоры логов вызывают у экспортера.

Описание

Экспортер отправляет записи лога во внешнюю систему: процессор логов передаёт ему пакеты записей, экспортер кодирует их и передаёт по своему протоколу. Встроенная реализация — ОтелЭкспортерЛогов (OTLP). Свой экспортер пишут для приёмника, который не принимает OTLP, или для тестов.

SDK реализацию не проверяет: процессор принимает любой объект и ищет методы по имени при вызове. Проверить класс заранее, например в тесте, можно валидатором библиотеки extends: ИнтерфейсыРеализованыКорректно(Экспортер) объекта Новый ВалидаторРеализации() бросает исключение, если метода интерфейса нет или его нельзя вызвать с числом параметров метода интерфейса — например, если у Экспортировать нет второго параметра.

Подключение экспортера

Экспортер передаётся процессору логов, а процессор регистрируется в провайдере логирования (ДобавитьПроцессор построителя ОтелПостроительПровайдераЛогирования):

ОтелПростойПроцессорЛогов — Новый ОтелПростойПроцессорЛогов(Экспортер): экспортирует каждую запись сразу, в потоке, который её записал (внутри Логгер.Записать);
ОтелПакетныйПроцессорЛогов — собирается из Новый ОтелБазовыйПакетныйПроцессор(Экспортер, "logs"): копит записи и экспортирует их пакетами в фоновом задании.

Процессоры не вызывают Экспортировать одновременно: следующий вызов начинается после завершения предыдущего. Повторной отправки процессоры не делают: повторы и параллельные запросы — забота экспортера (спецификация, раздел LogRecordExporter). СброситьБуфер и Закрыть могут вызываться одновременно с Экспортировать из другого потока — например, при закрытии провайдера во время фонового экспорта, — поэтому они должны быть потокобезопасны (спецификация, раздел Concurrency requirements).

Методы

Экспортировать

Экспортирует пакет записей лога (Export). Метод не должен блокироваться бесконечно (спецификация, раздел LogRecordExporter): соблюдайте Таймаут, а когда он не передан — собственный предел (у ОтелЭкспортерЛогов — 10 000 мс). После Закрыть возвращайте Ложь.

Записи экспортер только читает (ReadableLogRecord): ресурс и область инструментирования берутся из каждой записи (Ресурс(), ОбластьИнструментирования()).

Как процессоры вызывают метод:

Процессор	Пакет	`Таймаут`	Результат
Простой	одна запись	не передаётся	не проверяется; исключение пишется в лог ошибкой
Пакетный	до `МаксРазмерПакета` записей (по умолчанию 512)	время до срока экспорта: в фоновом экспорте — таймаут экспорта процессора (по умолчанию 30 000 мс), в `СброситьБуфер` и `Закрыть` процессора — остаток их срока; `Неопределено` — без ограничения	`Ложь`, неуспешный `ОтелРезультатЭкспорта` или исключение — сбой: пакет отбрасывается, в лог пишется предупреждение, а `СброситьБуфер` и `Закрыть` процессора, во время которых случился сбой, возвращают ошибку (таймаут, если к концу операции истёк её срок)

Простой процессор вызывает метод с одним параметром, пакетный — с двумя, поэтому второй параметр должен быть необязательным. Экспортер, у которого Экспортировать принимает один параметр, от пакетного процессора не получит ни одного пакета.

Параметр	Тип	По умолчанию	Описание
`МассивЗаписей`	`Массив` из `ОтелЗаписьЛога`	—	Записи лога
`Таймаут`	`Число`, `Неопределено`	`Неопределено`	Срок экспорта в миллисекундах; `Неопределено` — срок не задан

Возвращает: Булево — Истина при успехе, Ложь при сбое. Пакетный процессор принимает и ОтелРезультатЭкспорта (неуспешный — сбой), а другие значения, например Неопределено, считает успехом

СброситьБуфер

Как можно скорее завершает экспорт записей, полученных до вызова (ForceFlush, спецификация, раздел LogRecordExporter), в пределах таймаута. Экспортеру, который отправляет данные прямо в Экспортировать, делать нечего: он возвращает успех.

Кто вызывает:

простой процессор в своём СброситьБуфер — после завершения текущего экспорта, если тот завершился в срок, с временем, оставшимся до срока (0 — без ограничения). Параметр передаётся всегда, поэтому метод должен его принимать;
простой процессор в Закрыть, пакетный — в СброситьБуфер и Закрыть, после экспорта накопленных записей, если тот уложился в срок. Оставшееся время передаётся, если срок задан, иначе метод вызывается без параметра, поэтому параметр должен быть необязательным, как в интерфейсе.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Срок в миллисекундах, `0` — без ограничения

Возвращает: ОтелРезультатЭкспорта — ОтелРезультатыЭкспорта.Успех(), Ошибка() или Таймаут(). Простой процессор возвращает этот результат из своего СброситьБуфер; пакетный процессор и провайдер считают Ложь ошибкой, Неопределено — успехом, исключение — ошибкой

Закрыть

Завершает работу экспортера (Shutdown): освобождает ресурсы, после чего Экспортировать должен возвращать Ложь. Метод не должен блокироваться бесконечно (спецификация, раздел LogRecordExporter).

Процессор вызывает метод один раз, в своём Закрыть: после финального экспорта и СброситьБуфер экспортера, в пределах срока закрытия. Простой процессор, который не дождался текущего экспорта за срок, и пакетный, чей финальный экспорт не уложился в срок, закрывают экспортер без сброса буфера. Интерфейс объявляет метод без параметров; если у метода есть параметр и срок задан, процессор передаёт оставшееся время (после срока — 1 мс), иначе вызывает метод без параметра — такой параметр должен быть необязательным.

Возвращает: ОтелРезультатЗакрытия — ОтелРезультатыЗакрытия.Успех(), Ошибка(Описание) или Таймаут(). Неопределено считается успехом, Ложь — ошибкой, исключение — ошибкой с его описанием

Пример

Экспортер, который выводит записи лога в консоль:

bsl

// Файл КонсольныйЭкспортерЛогов.os
Перем Закрыт;

Функция Экспортировать(МассивЗаписей, Таймаут = Неопределено) Экспорт
    Если Закрыт Тогда
        Возврат Ложь;
    КонецЕсли;
    Для Каждого Запись Из МассивЗаписей Цикл
        Сообщить(СтрШаблон("[%1] %2: %3",
            Запись.ТекстСерьезности(), Запись.ОбластьИнструментирования().Имя(), Запись.Тело()));
    КонецЦикла;
    Возврат Истина;
КонецФункции

Функция СброситьБуфер(ТаймаутМс = 0) Экспорт
    // Своего буфера нет: записи выводятся в Экспортировать
    Возврат ОтелРезультатыЭкспорта.Успех();
КонецФункции

Функция Закрыть() Экспорт
    Закрыт = Истина;
    Возврат ОтелРезультатыЗакрытия.Успех();
КонецФункции

&Реализует("ИнтерфейсЭкспортерЛогов")
Процедура ПриСозданииОбъекта()
    Закрыт = Ложь;
КонецПроцедуры

Подключение:

bsl

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "КонсольныйЭкспортерЛогов.os"),
    "КонсольныйЭкспортерЛогов");

Базовый = Новый ОтелБазовыйПакетныйПроцессор(Новый КонсольныйЭкспортерЛогов(), "logs");
Процессор = Новый ПостроительНаследника(Новый ОтелПакетныйПроцессорЛогов(), Базовый).Построить();

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .ДобавитьПроцессор(Процессор)
    .Построить();

Логгер = Провайдер.ПолучитьЛоггер("my-library");
Запись = Логгер.СоздатьЗаписьЛога();
Запись.УстановитьСерьезность(ОтелСтепеньСерьезности.Info()).УстановитьТело("Заказ создан");
Логгер.Записать(Запись);

Провайдер.Закрыть(); // финальный экспорт накопленных записей

См. также

ИнтерфейсЭкспортерМетрик

Интерфейс экспортера метрик (push MetricExporter) — методы, которые периодический читатель метрик вызывает у экспортера.

Описание

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

Интерфейс — класс библиотеки с методами-заглушками и аннотацией &Интерфейс библиотеки extends. Класс экспортера объявляет, что реализует интерфейс, аннотацией &Реализует("ИнтерфейсЭкспортерМетрик") на конструкторе ПриСозданииОбъекта и определяет экспортные функции Экспортировать, СброситьБуфер и Закрыть. Кроме них читатель использует необязательные методы экспортера, если они есть: временную агрегацию и агрегацию по умолчанию задаёт экспортер (спецификация, раздел MetricReader).

SDK реализацию не проверяет: читатель принимает любой объект и ищет методы по имени при вызове. Проверить класс заранее, например в тесте, можно валидатором библиотеки extends: ИнтерфейсыРеализованыКорректно(Экспортер) объекта Новый ВалидаторРеализации() бросает исключение, если метода интерфейса нет или его нельзя вызвать с числом параметров метода интерфейса. Необязательные методы валидатор не проверяет.

Подключение экспортера

Экспортер передаётся ОтелПериодическийЧитательМетрик (Новый ОтелПериодическийЧитательМетрик(Экспортер, ИнтервалЭкспортаМс)), читатель регистрируется в провайдере метрик (ЗарегистрироватьЧитатель построителя ОтелПостроительПровайдераМетрик), а периодический сбор запускает Запустить() читателя.

Читатель не вызывает Экспортировать одновременно: сборы и экспорт идут по очереди. Повторной отправки читатель не делает: повторы — забота экспортера (спецификация, раздел Push Metric Exporter). СброситьБуфер и Закрыть могут вызываться одновременно с Экспортировать из другого потока — например, при закрытии провайдера во время фонового сбора, — поэтому они должны быть потокобезопасны (спецификация, раздел Concurrency requirements).

Методы

Экспортировать

Экспортирует данные сбора (Export). Читатель вызывает метод при каждом сборе: периодическом (после Запустить, раз в интервал), в своих СброситьБуфер, СброситьБуферБезОчистки и ПринудительноВыгрузитьСРезультатом (его вызывает СброситьБуфер провайдера метрик) и при финальном сборе в Закрыть. Если сбор не дал данных, метод не вызывается.

Пакет — метрики сбора: инструментов SDK и продюсеров метрик читателя. Если задан МаксРазмерПакетаЭкспорта читателя, данные делятся на пакеты не больше этого числа точек и экспортируются по очереди; точки одной метрики могут попасть в разные пакеты — каждая часть передаётся отдельным ОтелДанныеМетрики.
Таймаут — всегда число: меньшее из таймаута экспорта читателя (ТаймаутЭкспортаМс, по умолчанию 30 000 мс) и времени, оставшегося до срока операции; 0 — без ограничения. Метод не должен блокироваться бесконечно (спецификация, раздел Push Metric Exporter).
Временную агрегацию данных показывает ОтелДанныеМетрики.ВременнаяАгрегация(). О данных с неподдерживаемой агрегацией или временной агрегацией экспортер должен сообщать как об ошибке: её исправляют настройкой читателя (спецификация, раздел MetricExporter). ОтелЭкспортерМетрик в этом случае пишет предупреждение в лог и возвращает Ложь.
После Закрыть возвращайте Ложь.

Как читатель обрабатывает результат: Истина, успешный ОтелРезультатЭкспорта или успешный ОтелРезультатЗакрытия — успех. Любое другое значение, в том числе Неопределено, — сбой: таймаут, если экспортер вернул результат-таймаут или вызов длился дольше Таймаут, иначе ошибка. Исключение — ошибка и предупреждение в логе. Сбой экспорта делает результат сбора (СброситьБуфер, Закрыть читателя) ошибкой или таймаутом; данные неудачного экспорта читатель не хранит и повторно не отправляет. Результат периодического сбора никуда не передаётся, и Ложь читатель в лог не пишет: о причине сбоя экспортер сообщает сам.

Параметр	Тип	По умолчанию	Описание
`МассивДанныхМетрик`	`Массив` из `ОтелДанныеМетрики`	—	Данные метрик
`Таймаут`	`Число`	`Неопределено`	Срок экспорта в миллисекундах, `0` — без ограничения; читатель передаёт его всегда

Возвращает: Булево — Истина при успехе, Ложь при сбое; допускается и ОтелРезультатЭкспорта (ОтелРезультатыЭкспорта.Таймаут() читатель учитывает как таймаут)

СброситьБуфер

Как можно скорее завершает экспорт метрик, полученных до вызова (ForceFlush, спецификация, раздел Push Metric Exporter), в пределах таймаута. Экспортеру, который отправляет данные прямо в Экспортировать, делать нечего: он возвращает успех.

Вызывается из ПринудительноВыгрузитьСРезультатом читателя (ForceFlush, его вызывает СброситьБуфер провайдера метрик) после сбора и экспорта — даже если они завершились сбоем или срок уже истёк, — и только если у экспортера нет функции ПринудительноВыгрузитьСРезультатом. СброситьБуфер читателя этот метод не вызывает. Оставшееся время передаётся, если у метода есть параметр и срок задан (после срока — 1 мс), иначе метод вызывается без параметра — параметр должен быть необязательным, как в интерфейсе.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Срок в миллисекундах, `0` — без ограничения

Возвращает: ОтелРезультатЭкспорта — ОтелРезультатыЭкспорта.Успех(), Ошибка() или Таймаут(). Ложь читатель считает ошибкой, Неопределено — успехом, исключение — ошибкой

Закрыть

Вызывается из Закрыть читателя (его вызывает Закрыть провайдера метрик) один раз: после финального сбора и экспорта, даже если они завершились сбоем, в пределах срока закрытия. Интерфейс объявляет метод без параметров; если у метода есть параметр и срок задан, читатель передаёт оставшееся время (после срока — 1 мс), иначе вызывает метод без параметра — такой параметр должен быть необязательным.

Необязательные методы

Этих методов в интерфейсе нет: читатель вызывает их, если экспортер их определяет.

ПолучитьВременнуюАгрегацию

Возвращает временную агрегацию (temporality) для типа инструмента: читатель собирает потоки метрик с той временной агрегацией, которую задаёт экспортер. Вызывается при каждом сборе для каждого потока метрик. ОтелВременнаяАгрегация.Дельта() — дельта, любое другое значение — кумулятивная. Без метода, а также если он бросает исключение, все потоки собираются кумулятивно.

Готовые селекторы даёт ОтелСелекторВременнойАгрегации: селектор вызывается как Селектор.Применить(ТипИнструмента).

Параметр	Тип	По умолчанию	Описание
`ТипИнструмента`	`Строка`	—	`"counter"`, `"up_down_counter"`, `"histogram"` (и для экспоненциальной гистограммы), `"gauge"`, `"observable_counter"`, `"observable_up_down_counter"`, `"observable_gauge"`

Возвращает: Число — значение из ОтелВременнаяАгрегация

АгрегацияПоУмолчанию

Возвращает агрегацию по умолчанию для вида инструмента. Читатель применяет её к потокам, для которых агрегацию не задали View и сам инструмент (экспоненциальная гистограмма получает свою агрегацию при создании), если читателю не задана своя агрегация для этого вида (УстановитьАгрегациюПоУмолчанию, агрегация гистограмм конструктора). Пустое значение — агрегация спецификации для вида. Агрегация, неизвестная или несовместимая с видом (например, гистограмма для асинхронного инструмента), заменяется агрегацией по умолчанию с предупреждением в логе.

Параметр	Тип	По умолчанию	Описание
`ВидИнструмента`	`Строка`	—	`"Counter"`, `"UpDownCounter"`, `"Histogram"`, `"Gauge"`, `"ObservableCounter"`, `"ObservableUpDownCounter"`, `"ObservableGauge"`

Возвращает: Строка, Соответствие — агрегация: "sum", "last_value", "explicit_bucket_histogram", "base2_exponential_bucket_histogram", "drop", "default" или конфигурация из ОтелАгрегация

ПринудительноВыгрузитьСРезультатом

Если метод есть, ПринудительноВыгрузитьСРезультатом читателя (ForceFlush) вызывает его вместо СброситьБуфер — так же: после сбора и экспорта, даже после их сбоя или истечения срока.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Время до срока в миллисекундах (после срока — 1 мс). Если срок не задан, метод вызывается без параметра, поэтому параметр должен быть необязательным

Возвращает: ОтелРезультатЗакрытия — результат сброса

Пример

Экспортер, который выводит метрики в консоль и собирает счетчики и гистограммы дельтами:

bsl

// Файл КонсольныйЭкспортерМетрик.os
Перем Закрыт;
Перем СелекторВременнойАгрегации;

Функция Экспортировать(МассивДанныхМетрик, Таймаут = Неопределено) Экспорт
    Если Закрыт Тогда
        Возврат Ложь;
    КонецЕсли;
    Для Каждого Данные Из МассивДанныхМетрик Цикл
        Сообщить(СтрШаблон("%1 (%2): точек данных %3",
            Данные.Имя(), Данные.ТипМетрики(), Данные.ТочкиДанных().Количество()));
    КонецЦикла;
    Возврат Истина;
КонецФункции

Функция СброситьБуфер(ТаймаутМс = 0) Экспорт
    // Своего буфера нет: данные выводятся в Экспортировать
    Возврат ОтелРезультатыЭкспорта.Успех();
КонецФункции

Функция Закрыть() Экспорт
    Закрыт = Истина;
    Возврат ОтелРезультатыЗакрытия.Успех();
КонецФункции

// Необязательный метод: без него читатель собирает все метрики кумулятивно
Функция ПолучитьВременнуюАгрегацию(ТипИнструмента) Экспорт
    Возврат СелекторВременнойАгрегации.Применить(ТипИнструмента);
КонецФункции

&Реализует("ИнтерфейсЭкспортерМетрик")
Процедура ПриСозданииОбъекта()
    Закрыт = Ложь;
    СелекторВременнойАгрегации = ОтелСелекторВременнойАгрегации.ПредпочтительноДельта();
КонецПроцедуры

Подключение:

bsl

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "КонсольныйЭкспортерМетрик.os"),
    "КонсольныйЭкспортерМетрик");

Читатель = Новый ОтелПериодическийЧитательМетрик(Новый КонсольныйЭкспортерМетрик(), 60000);
Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ЗарегистрироватьЧитатель(Читатель)
    .Построить();
Читатель.Запустить();

Счетчик = Провайдер.ПолучитьМетр("my-library").СоздатьСчетчик("orders.created");
Счетчик.Добавить(1);

Провайдер.СброситьБуфер(); // сбор и экспорт, не дожидаясь интервала
Провайдер.Закрыть();

См. также

ИнтерфейсЭкспортерСпанов

Интерфейс экспортера спанов (SpanExporter) — методы, которые процессоры спанов вызывают у экспортера.

Описание

Экспортер отправляет завершённые спаны во внешнюю систему: процессор спанов передаёт ему пакеты спанов, экспортер кодирует их и передаёт по своему протоколу. Встроенная реализация — ОтелЭкспортерСпанов (OTLP). Свой экспортер пишут для приёмника, который не принимает OTLP, или для тестов.

Подключение экспортера

Экспортер передаётся процессору спанов, а процессор регистрируется в провайдере трассировки (ДобавитьПроцессор построителя ОтелПостроительПровайдераТрассировки):

ОтелПростойПроцессорСпанов — Новый ОтелПростойПроцессорСпанов(Экспортер): экспортирует каждый спан при завершении, в потоке, который завершил спан;
ОтелПакетныйПроцессорСпанов — собирается из Новый ОтелБазовыйПакетныйПроцессор(Экспортер, "traces"): копит спаны и экспортирует их пакетами в фоновом задании.

Оба процессора передают экспортеру только сэмплированные спаны (с флагом sampled) и не вызывают Экспортировать одновременно: следующий вызов начинается после завершения предыдущего. Повторной отправки процессоры не делают: повторы и параллельные запросы — забота экспортера (спецификация, раздел Span Exporter). СброситьБуфер и Закрыть могут вызываться одновременно с Экспортировать из другого потока — например, при закрытии провайдера во время фонового экспорта, — поэтому они должны быть потокобезопасны (спецификация, раздел Concurrency requirements).

Методы

Экспортировать

Экспортирует пакет завершённых спанов (Export). Метод не должен блокироваться бесконечно (спецификация, раздел Span Exporter): соблюдайте Таймаут, а когда он не передан — собственный предел (у ОтелЭкспортерСпанов — 10 000 мс). После Закрыть возвращайте Ложь.

Как процессоры вызывают метод:

Процессор	Пакет	`Таймаут`	Результат
Простой	один спан	не передаётся	не проверяется; исключение простой процессор пробрасывает, его перехватывает и пишет в лог предупреждением композитный процессор провайдера
Пакетный	до `МаксРазмерПакета` спанов (по умолчанию 512)	время до срока экспорта: в фоновом экспорте — таймаут экспорта процессора (по умолчанию 30 000 мс), в `СброситьБуфер` и `Закрыть` процессора — остаток их срока; `Неопределено` — без ограничения	`Ложь`, неуспешный `ОтелРезультатЭкспорта` или исключение — сбой: пакет отбрасывается, в лог пишется предупреждение, а `СброситьБуфер` и `Закрыть` процессора, во время которых случился сбой, возвращают ошибку (таймаут, если к концу операции истёк её срок)

Параметр	Тип	По умолчанию	Описание
`МассивСпанов`	`Массив` из `ОтелСпан`	—	Завершённые спаны
`Таймаут`	`Число`, `Неопределено`	`Неопределено`	Срок экспорта в миллисекундах; `Неопределено` — срок не задан

СброситьБуфер

Как можно скорее завершает экспорт спанов, полученных до вызова (ForceFlush, спецификация, раздел Span Exporter), в пределах таймаута. Экспортеру, который отправляет данные прямо в Экспортировать, делать нечего: он возвращает успех.

Кто вызывает:

простой процессор в своём СброситьБуфер — после завершения текущего экспорта, если тот завершился в срок, с временем, оставшимся до срока (0 — без ограничения). Параметр передаётся всегда, поэтому метод должен его принимать;
простой процессор в Закрыть, пакетный — в СброситьБуфер и Закрыть, после экспорта накопленных спанов, если тот уложился в срок. Оставшееся время передаётся, если срок задан, иначе метод вызывается без параметра, поэтому параметр должен быть необязательным, как в интерфейсе.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Срок в миллисекундах, `0` — без ограничения

Закрыть

Пример

Экспортер, который выводит завершённые спаны в консоль:

bsl

// Файл КонсольныйЭкспортерСпанов.os
Перем Закрыт;

Функция Экспортировать(МассивСпанов, Таймаут = Неопределено) Экспорт
    Если Закрыт Тогда
        Возврат Ложь;
    КонецЕсли;
    Для Каждого Спан Из МассивСпанов Цикл
        КонтекстСпана = Спан.КонтекстСпана();
        Сообщить(СтрШаблон("%1 trace_id=%2 span_id=%3",
            Спан.Имя(), КонтекстСпана.ИдТрассировки(), КонтекстСпана.ИдСпана()));
    КонецЦикла;
    Возврат Истина;
КонецФункции

Функция СброситьБуфер(ТаймаутМс = 0) Экспорт
    // Своего буфера нет: спаны выводятся в Экспортировать
    Возврат ОтелРезультатыЭкспорта.Успех();
КонецФункции

Функция Закрыть() Экспорт
    Закрыт = Истина;
    Возврат ОтелРезультатыЗакрытия.Успех();
КонецФункции

&Реализует("ИнтерфейсЭкспортерСпанов")
Процедура ПриСозданииОбъекта()
    Закрыт = Ложь;
КонецПроцедуры

Подключение:

bsl

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "КонсольныйЭкспортерСпанов.os"),
    "КонсольныйЭкспортерСпанов");

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .ДобавитьПроцессор(Новый ОтелПростойПроцессорСпанов(Новый КонсольныйЭкспортерСпанов()))
    .Построить();

Трассировщик = Провайдер.ПолучитьТрассировщик("my-library");
Спан = Трассировщик.НачатьСпан("обработка-заказа");
Спан.Завершить(); // простой процессор сразу передаёт спан экспортеру

Провайдер.Закрыть();

// С пакетным процессором
Базовый = Новый ОтелБазовыйПакетныйПроцессор(Новый КонсольныйЭкспортерСпанов(), "traces");
Процессор = Новый ПостроительНаследника(Новый ОтелПакетныйПроцессорСпанов(), Базовый).Построить();

См. также

ОтелGrpcТранспорт

gRPC-транспорт для отправки телеметрии по протоколу OTLP.

Описание

Обеспечивает отправку данных трассировки, метрик и логов через gRPC на адреса OTLP-совместимых коллекторов (Grafana LGTM, OpenTelemetry Collector и т.д.). Использует библиотеку oint (OPI_GRPC) для gRPC-вызовов.

Реализует тот же интерфейс Отправить(Путь, Данные, ТаймаутМс), что и ОтелHttpТранспорт, поэтому все существующие экспортеры (спаны, логи, метрики) работают с обоими транспортами.

Данные передаются в формате OTLP JSON (camelCase ключи); транспорт автоматически конвертирует их в формат protobuf (snake_case ключи) через внутренний конвертер.

Временные ошибки повторяются с экспоненциальной задержкой и jitter. По спецификации OTLP/gRPC это коды CANCELLED, DEADLINE_EXCEEDED, ABORTED, OUT_OF_RANGE, UNAVAILABLE, DATA_LOSS, а RESOURCE_EXHAUSTED — только если сервер вернул RetryInfo. Код распознаётся в обеих записях: DeadlineExceeded (так его пишет клиент tonic в OPI_GRPC) и DEADLINE_EXCEEDED.

Если сервер прислал в деталях статуса RetryInfo (OTLP/gRPC Throttling), первый повтор идёт не раньше retry_delay, а каждый следующий ждёт вдвое дольше. Если retry_delay не меньше времени, оставшегося до срока отправки, повтор в срок не уложится: отправка прекращается сразу, ошибка пишется в лог. Детали статуса транспорт берёт из текста ошибки OPI_GRPC: клиент tonic пишет в него сериализованный google.rpc.Status списком байтов (details: [8, 14, ...]).

Защищённость соединения задаёт схема адреса: https:// — соединение с TLS, http:// — без TLS. По TLS сертификат сервера проверяется всегда: по системным и встроенным корневым сертификатам и по ФайлСертификата из настроек TLS (собственный CA коллектора). Адрес без схемы защищён TLS, если в настройках TLS не включён Insecure; с Insecure = Истина соединение идёт без TLS. Схема важнее Insecure: Insecure не отключает TLS для https:// и не включает его для http://.

Если коллектор недоступен при создании транспорта, соединение открывается заново при отправке (с теми же повторами); после Закрыть() соединение больше не открывается. Ошибки компоненты OPI_GRPC при открытии соединения записываются в лог и не выбрасываются из конструктора.

Транспорт добавляет в метаданные вызова user-agent со стандартной строкой OTel-OTLP-Exporter-OneScript/<версия>. Пользовательские метаданные user-agent (в любом регистре) — идентификатор продукта: он ставится перед стандартной строкой, например MyDistribution/1.2.3 OTel-OTLP-Exporter-OneScript/1.1.0. До сервера метаданные user-agent пока не доходят — см. ограничения ниже.

Ограничения клиента OPI_GRPC:

сжатие (gzip) не поддерживается, данные отправляются без сжатия (OpenIntegrations#112);
mTLS (клиентский ключ и сертификат) не поддерживается (OpenIntegrations#102);
максимальный размер ответа фиксирован клиентом gRPC — 4 MiB (значение по умолчанию спецификации), настроить его нельзя (OpenIntegrations#113);
заголовок user-agent задаёт сам клиент tonic внутри OPI_GRPC: метаданные user-agent до сервера не доходят, сервер получает tonic/0.13.1. User-Agent в tonic задаётся только при создании gRPC-канала (Endpoint::user_agent), а такой настройки OPI_GRPC пока не даёт (OpenIntegrations#111);
таймаута подключения нет: открытие соединения (в конструкторе и при отправке) и переподключение внутри вызова сроком отправки не ограничены. Сервер, который принял TCP-соединение и молчит (TLS-рукопожатие не завершается), держит конструктор или отправку, пока сам не закроет соединение; адрес, который не отвечает на TCP-подключение, — до системного таймаута подключения (в Linux около 2 минут). Пока это не исправлено, экспорт по gRPC может блокироваться дольше срока: требования спецификации «Export MUST NOT block indefinitely» и «Shutdown/ForceFlush SHOULD complete or abort within some timeout» для gRPC выполняются не полностью (OpenIntegrations#114).

Конструктор

bsl

Новый ОтелGrpcТранспорт(
    Адрес,
    НастройкиTls,
    Метаданные,
    КаталогProto,
    Таймаут,
    НовыйМаксПопыток
)

Параметр	Тип	По умолчанию	Описание
`Адрес`	Строка	—	Адрес OTLP-коллектора, например `"http://localhost:4317"`. `https://` — соединение с TLS, `http://` — без TLS; адрес без схемы защищён TLS, если не включён `Insecure`
`НастройкиTls`	ОтелНастройкиTls	`Неопределено`	Настройки TLS: `ФайлСертификата` — собственный CA для проверки сервера, `Insecure` — адрес без схемы без TLS
`Метаданные`	Соответствие	`Неопределено`	Метаданные gRPC, отправляемые с каждым вызовом
`КаталогProto`	Строка	`""`	Каталог с OTLP `.proto` файлами (по умолчанию `proto/` рядом с библиотекой)
`Таймаут`	Число	`10000`	Таймаут gRPC-вызова в миллисекундах
`НовыйМаксПопыток`	Число	`3`	Максимальное количество попыток отправки

Методы

Отправить

Отправляет данные на указанный путь OTLP-адреса через gRPC в пределах срока. Автоматически конвертирует OTLP JSON в формат protobuf.

Отправка идёт в вызывающем потоке, все попытки и паузы между ними укладываются в срок: таймаут вызова не больше времени, оставшегося до срока, после срока новая попытка не начинается, а пауза прерывается. Открытие соединения и переподключение в срок не укладываются — см. ограничения OPI_GRPC выше (OpenIntegrations#114).

Параметр	Тип	По умолчанию	Описание
`Путь`	Строка	—	Путь OTLP-адреса, например `"/v1/traces"`
`Данные`	Соответствие	—	Данные для отправки в формате OTLP JSON
`ТаймаутМс`	Число	`0`	Срок отправки в миллисекундах, `0` — без ограничения

Возвращает: Булево — Истина, если отправка прошла успешно

Закрыть

Закрывает gRPC-соединение. После вызова транспорт перестаёт принимать запросы и не открывает соединение заново. Повторный вызов ничего не делает.

Транспорт, созданный автоконфигурацией, закрывает экспортер при закрытии SDK. Транспорт, который пользователь передал экспортеру, пользователь закрывает сам: один транспорт может обслуживать экспортеры всех трёх сигналов.

МаксРазмерЗапроса

Возвращает максимальный размер запроса в байтах. Размер считается до сжатия, запрос больше лимита не отправляется (ошибка в логе, Отправить возвращает Ложь).

Возвращает: Число — по умолчанию 67108864 (64 MiB); 0 — без ограничения

УстановитьМаксРазмерЗапроса

Устанавливает максимальный размер запроса в байтах.

Параметр	Тип	По умолчанию	Описание
`Значение`	Число	—	Максимальный размер запроса в байтах; `0` — без ограничения

Возвращает: ОтелGrpcТранспорт — этот транспорт

Адрес

Возвращает адрес коллектора, с которым соединяется транспорт. Адресу без схемы транспорт задаёт схему по Insecure.

Возвращает: Строка — адрес со схемой: https:// — соединение с TLS, http:// — без TLS

ПолучитьМетаданные

Возвращает метаданные gRPC, отправляемые с каждым вызовом.

Возвращает: Соответствие — метаданные gRPC

ПолучитьНастройкиTls

Возвращает настройки TLS транспорта.

Возвращает: ОтелНастройкиTls, Неопределено — настройки TLS или Неопределено, если не заданы

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

Экспортированы для служебных вызовов (в OneScript нет внутренней видимости): ВыполнитьОднуПопытку и РассчитатьЗадержкуRetryInfo через Действие вызывает стратегия повтора библиотеки resilience в Отправить, остальные — сам транспорт и модульные тесты. Приложению вызывать их не нужно:

ВыполнитьОднуПопытку — одна попытка gRPC-вызова, которую повторяет Отправить: при необходимости открывает соединение, ограничивает вызов временем до срока; успешный ответ — Истина; повторяемая ошибка или недоступный коллектор — исключение, чтобы стратегия повторила вызов (с retry_delay, если сервер прислал RetryInfo); неповторяемая ошибка, закрытый транспорт или retry_delay не раньше срока — Ложь;
ОшибкаПовторяемая — определяет по тексту ошибки OPI_GRPC, повторять ли вызов: коды CANCELLED, DEADLINE_EXCEEDED, ABORTED, OUT_OF_RANGE, UNAVAILABLE, DATA_LOSS, а RESOURCE_EXHAUSTED — только с RetryInfo;
ЗадержкаRetryInfo — retry_delay из RetryInfo в деталях статуса (текст ошибки OPI_GRPC) в миллисекундах; Неопределено, если RetryInfo нет;
РассчитатьЗадержкуRetryInfo — задержка перед повтором для стратегии повтора: retry_delay, удвоенная за каждую следующую попытку; Неопределено, если RetryInfo с задержкой нет (действует экспоненциальная задержка стратегии).

Пример

bsl

#Использовать opentelemetry

// Простой gRPC-транспорт
Транспорт = Новый ОтелGrpcТранспорт("http://localhost:4317");

// С метаданными авторизации
Метаданные = Новый Соответствие();
Метаданные.Вставить("authorization", "Bearer mytoken");
Транспорт = Новый ОтелGrpcТранспорт("http://localhost:4317", , Метаданные);

// С TLS и собственным CA коллектора
НастройкиTls = Новый ОтелНастройкиTls();
НастройкиTls.ФайлСертификата = "/etc/ssl/ca.crt";
Транспорт = Новый ОтелGrpcТранспорт("https://collector.example.com", НастройкиTls);

// Адрес без схемы: без Insecure соединение защищено TLS, с Insecure - без TLS
НастройкиTls = Новый ОтелНастройкиTls();
НастройкиTls.Insecure = Истина;
Транспорт = Новый ОтелGrpcТранспорт("collector:4317", НастройкиTls);

// Использование с экспортером
ЭкспортерСпанов = Новый ОтелЭкспортерСпанов(Транспорт);
// Транспорт создан пользователем: после закрытия SDK закрыть соединение
Транспорт.Закрыть();

ОтелHttpТранспорт

HTTP-транспорт для отправки телеметрии по протоколу OTLP.

Описание

Обеспечивает отправку данных трассировки, метрик и логов в формате JSON или protobuf по HTTP на адреса OTLP-совместимых коллекторов (Grafana LGTM, OpenTelemetry Collector и т.д.). Использует библиотеку 1connector для HTTP-запросов.

При получении HTTP-кодов 429, 502, 503, 504 и при ошибке соединения транспорт повторяет попытку с экспоненциальной задержкой и jitter или с паузой из Retry-After. Попытки и паузы укладываются в срок отправки, который передаёт экспортёр (см. Отправить).

Поддерживает протоколы http/protobuf (по умолчанию, согласно спецификации OTel) и http/json, gzip-сжатие тела запроса, а также TLS-настройки через ОтелНастройкиTls.

Запрос больше максимального размера (по умолчанию 64 MiB, размер до сжатия) не отправляется, ответ больше максимального размера (по умолчанию 4 MiB) не принимается — в обоих случаях ошибка пишется в лог, а Отправить возвращает Ложь.

Пользовательский заголовок User-Agent (в любом регистре) — идентификатор продукта: он добавляется перед стандартным OTel-OTLP-Exporter-OneScript/<версия>, например MyDistribution/1.2.3 OTel-OTLP-Exporter-OneScript/1.1.0.

HTTP-клиент OneScript не применяет файлы сертификатов (ФайлСертификата, ФайлКлиентскогоКлюча, ФайлКлиентскогоСертификата): транспорт предупреждает об этом при создании. Insecure по спецификации относится только к gRPC: защищённость HTTP-соединения задаёт схема адреса.

Безопасность. HTTP-клиент OneScript (HTTPСоединение, через него работает 1connector) не проверяет сертификат сервера по HTTPS: соединение шифруется, но принимается любой сертификат, в том числе самоподписанный или выданный на другое имя. Подлинность коллектора не подтверждается, и телеметрию получит любой сервер, перехвативший соединение. Если это важно, используйте ОтелGrpcТранспорт — он проверяет сертификат сервера, — или доверенную сеть до коллектора.

Конструктор

bsl

Новый ОтелHttpТранспорт(
    Адрес,
    НовыеЗаголовки,
    Таймаут,
    НовыйМаксПопыток,
    Компрессия,
    НастройкиTls,
    НовыйПротокол,
    НовыйСигнал
)

Параметр	Тип	По умолчанию	Описание
`Адрес`	Строка	—	Адрес OTLP-коллектора, например `"http://localhost:4318"`
`НовыеЗаголовки`	Соответствие	`Неопределено`	Дополнительные HTTP-заголовки, отправляемые с каждым запросом
`Таймаут`	Число	`10`	Таймаут HTTP-запроса в секундах, `0` — без ограничения
`НовыйМаксПопыток`	Число	`3`	Максимальное количество попыток отправки при повторяемых ошибках
`Компрессия`	Строка	`Неопределено`	Алгоритм сжатия: `"gzip"` или `Неопределено` для отключения
`НастройкиTls`	ОтелНастройкиTls	`Неопределено`	Настройки TLS для защищённых соединений
`НовыйПротокол`	Строка	`"http/protobuf"`	Протокол OTLP: `"http/protobuf"` или `"http/json"`
`НовыйСигнал`	Строка	`""`	Сигнал телеметрии: `"traces"`, `"metrics"`, `"logs"` или пустая строка

Методы

Отправить

Отправляет данные на указанный путь OTLP-адреса в пределах срока. При получении HTTP 429/502/503/504 и при ошибке соединения повторяет попытку с экспоненциальной задержкой или с паузой из Retry-After. Поддерживает оба протокола: http/json и http/protobuf.

Retry-After — число секунд или дата HTTP в любом из трёх форматов RFC 7231: IMF-fixdate (Sun, 06 Nov 1994 08:49:37 GMT), RFC 850 (Sunday, 06-Nov-94 08:49:37 GMT) и asctime (Sun Nov 6 08:49:37 1994). Прошедшая дата не задерживает повтор.

Отправка идёт в вызывающем потоке, все попытки и паузы между ними укладываются в срок: таймаут запроса не больше времени, оставшегося до срока, после срока новая попытка не начинается, а пауза прерывается.

Параметр	Тип	По умолчанию	Описание
`Путь`	Строка	—	Путь OTLP-адреса, например `"/v1/traces"`
`Данные`	Соответствие	—	Данные для отправки в формате OTLP JSON
`ТаймаутМс`	Число	`0`	Срок отправки в миллисекундах, `0` — без ограничения

Возвращает: Булево — Истина, если отправка прошла успешно; Ложь при ошибке и после Закрыть

Ограничения HTTP-клиента OneScript:

таймаут запроса задаётся в секундах, поэтому время до срока округляется вверх до секунды и отправка может закончиться позже срока меньше чем на секунду;
таймаут ограничивает соединение и ожидание заголовков ответа, но не чтение тела: если сервер отправил заголовки и перестал отвечать, тело ждёт около 5 минут при любом сроке (EvilBeaver/OneScript#1789).

Если сервер разрешает повтор (Retry-After) только после срока, повторить в срок нельзя: транспорт сразу возвращает Ложь и пишет ошибку в лог. Экспоненциальная пауза, которая не успевает закончиться до срока, прерывается на сроке.

Закрыть

Закрывает транспорт: после вызова Отправить возвращает Ложь и пишет ошибку в лог. Соединений между запросами HTTP-транспорт не держит (каждая отправка — отдельный запрос), поэтому освобождать нечего. Повторный вызов ничего не делает.

Транспорт, созданный автоконфигурацией или по файлу конфигурации, закрывает экспортер при закрытии SDK. Транспорт, который пользователь передал экспортеру, пользователь закрывает сам.

ПолучитьЗаголовки

Возвращает HTTP-заголовки, отправляемые с каждым запросом.

Возвращает: Соответствие — заголовки HTTP-запроса

Таймаут

Возвращает таймаут HTTP-запроса в секундах. Заданный 0 (без ограничения) возвращается как 2147483 (2^31-1 мс): библиотека 1connector считает 0 незаданным и ограничивает запрос 30 с, поэтому транспорт передаёт ей очень большой срок, как допускает спецификация.

Возвращает: Число — таймаут в секундах

ПолучитьНастройкиTls

Возвращает настройки TLS транспорта.

Возвращает: ОтелНастройкиTls, Неопределено — настройки TLS или Неопределено, если не заданы

МаксРазмерЗапроса / УстановитьМаксРазмерЗапроса

Максимальный размер запроса в байтах до сжатия (Max Request Size); 0 — без ограничения. Установщик возвращает ОтелHttpТранспорт для цепочки вызовов.

Возвращает: Число — по умолчанию 67108864 (64 MiB)

МаксРазмерОтвета / УстановитьМаксРазмерОтвета

Максимальный размер принимаемого ответа в байтах (Max Response Size). Установщик возвращает ОтелHttpТранспорт для цепочки вызовов.

Возвращает: Число — по умолчанию 4194304 (4 MiB)

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

Экспортированы для служебных вызовов (в OneScript нет внутренней видимости): их через Действие вызывает стратегия повтора библиотеки resilience в Отправить. Приложению вызывать их не нужно:

ВыполнитьОднуПопытку — одна попытка HTTP-запроса, которую повторяет Отправить: таймаут запроса не больше таймаута транспорта и времени до срока, округлённого вверх до секунды; код 2xx — Истина; коды 429, 502, 503, 504 — исключение с задержкой из Retry-After, чтобы стратегия повторила запрос, а если Retry-After разрешает повтор не раньше срока — Ложь; другой код или ответ больше максимального размера — Ложь; ошибка соединения выходит исключением и тоже повторяется;
РассчитатьЗадержкуRetryAfter — задержка перед повтором для стратегии повтора: пауза из Retry-After в миллисекундах; Неопределено, если заголовка нет или пауза нулевая (действует экспоненциальная задержка стратегии).

Пример

bsl

#Использовать opentelemetry

// Простой HTTP-транспорт
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");

// С заголовками авторизации и gzip-сжатием
Заголовки = Новый Соответствие();
Заголовки.Вставить("Authorization", "Bearer mytoken");
Транспорт = Новый ОтелHttpТранспорт("https://collector.example.com", Заголовки, 30, 5, "gzip");

// С идентификатором дистрибутива в User-Agent и лимитом размера запроса 16 MiB
Заголовки = Новый Соответствие();
Заголовки.Вставить("User-Agent", "MyDistribution/1.2.3");
Транспорт = Новый ОтелHttpТранспорт("https://collector.example.com", Заголовки)
    .УстановитьМаксРазмерЗапроса(16777216);

// Использование с экспортером спанов
ЭкспортерСпанов = Новый ОтелЭкспортерСпанов(Транспорт);

ОтелВПамятьТранспорт

Транспорт в памяти (InMemoryTransport) для тестирования.

Описание

Реализует тот же интерфейс Отправить(Путь, Данные, ТаймаутМс), что и ОтелHttpТранспорт и ОтелGrpcТранспорт. Вместо отправки по сети сохраняет данные в массив для последующей проверки в тестах.

Является потокобезопасным: все операции защищены БлокировкаРесурса для корректной работы при конкурентном вызове.

Конструктор

Конструктор без параметров. При создании инициализирует пустой массив отправленных данных и признак закрытия в Ложь.

bsl

Новый ОтелВПамятьТранспорт()

Методы

Отправить

Сохраняет данные в память. Если транспорт закрыт, возвращает Ложь. Сохранение не ждёт, поэтому срок отправки не используется.

Параметр	Тип	По умолчанию	Описание
`Путь`	Строка	—	Путь адреса, например `"/v1/traces"`
`Данные`	Соответствие	—	Данные в формате OTLP JSON
`ТаймаутМс`	Число	`0`	Срок отправки в миллисекундах, `0` — без ограничения

Возвращает: Булево — Истина, если транспорт не закрыт и данные сохранены

ПолучитьОтправленные

Возвращает все сохранённые отправки.

Возвращает: Массив из Соответствие — каждый элемент содержит ключи "Путь" и "Данные"

Очистить

Очищает все сохранённые отправки. Транспорт остаётся рабочим.

Закрыть

Завершает работу транспорта. После вызова метод Отправить() возвращает Ложь.

Пример

bsl

#Использовать opentelemetry

// Создать транспорт для тестирования
Транспорт = Новый ОтелВПамятьТранспорт();

// Подключить к экспортеру
Экспортер = Новый ОтелЭкспортерСпанов(Транспорт);

// ... выполнить операции, создающие спаны ...

// Проверить результаты
Отправленные = Транспорт.ПолучитьОтправленные();
Если Отправленные.Количество() > 0 Тогда
    ПерваяОтправка = Отправленные[0];
    Сообщить("Путь: " + ПерваяОтправка["Путь"]);
    // Данные["resourceSpans"] - отправленные спаны
КонецЕсли;

// Сбросить для следующего теста
Транспорт.Очистить();

ОтелКонсольныйТранспорт

Консольный транспорт экспортеров OTLP — экспортер console файла конфигурации.

Описание

Реализует тот же интерфейс Отправить(Путь, Данные, ТаймаутМс), что и ОтелHttpТранспорт и ОтелGrpcТранспорт. Вместо отправки по сети выводит данные в стандартный вывод (Сообщить): каждая отправка — одна строка OTLP JSON, например {"resourceSpans":[...]}. С ОтелЭкспортерСпанов, ОтелЭкспортерЛогов и ОтелЭкспортерМетрик даёт консольные экспортеры спанов, записей логов и метрик — для отладки и локальной разработки. Формат вывода — OTLP JSON, как в теле запроса http/json; путь сигнала в вывод не попадает.

Транспорт потокобезопасен: строки разных отправок не перемешиваются.

Конструктор

Конструктор без параметров.

bsl

Новый ОтелКонсольныйТранспорт()

Методы

Отправить

Выводит данные одной строкой OTLP JSON. Если транспорт закрыт, ничего не выводит и возвращает Ложь. Вывод не ждёт сети, поэтому срок отправки не используется.

Параметр	Тип	По умолчанию	Описание
`Путь`	Строка	—	Путь сигнала, например `"/v1/traces"`
`Данные`	Соответствие	—	Данные в формате OTLP JSON
`ТаймаутМс`	Число	`0`	Срок отправки в миллисекундах, `0` — без ограничения

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

Закрыть

Завершает работу транспорта. После вызова метод Отправить() ничего не выводит и возвращает Ложь.

Пример

bsl

#Использовать opentelemetry

Экспортер = Новый ОтелЭкспортерСпанов(Новый ОтелКонсольныйТранспорт());
Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .ДобавитьПроцессор(Новый ОтелПростойПроцессорСпанов(Экспортер))
    .Построить();

Провайдер.ПолучитьТрассировщик("пример").НачатьСпан("операция").Завершить();
// В стандартный вывод: {"resourceSpans":[{"resource":...,"scopeSpans":[...]}]}

Провайдер.Закрыть();

См. также

ОтелВПамятьТранспорт — транспорт в памяти для тестов
ОтелКонфигурация — экспортер console в файле конфигурации

ОтелНастройкиTls

Настройки TLS для OTLP-транспортов.

Описание

Используется для передачи параметров TLS в ОтелHttpТранспорт и ОтелGrpcТранспорт. Соответствует спецификации OTLP Exporter: поля Insecure, Certificate File, Client key file, Client certificate file.

Примечание: поля ФайлКлиентскогоКлюча и ФайлКлиентскогоСертификата (mTLS-клиентский сертификат) принимаются в настройках, но пока не применяются ни одним транспортом:
HTTP-транспорт настройки не применяет. HTTP-клиент OneScript (HTTPСоединение, через него работает 1connector) не умеет задавать клиентский и корневой сертификаты: ФайлСертификата HTTP-транспорт тоже не использует. Сертификат сервера по HTTPS этот клиент не проверяет вообще — см. ОтелHttpТранспорт. Insecure по спецификации относится только к gRPC: защищённость HTTP-соединения задаёт схема адреса.
gRPC-транспорт использует ФайлСертификата и Insecure. ФайлСертификата — собственный CA для проверки сервера по TLS, Insecure действует только на адрес без схемы: Истина — соединение без TLS. Клиентские ключ и сертификат он игнорирует с предупреждением: mTLS не поддерживает библиотека OPI_GRPC (OpenIntegrations#102).
Сводная таблица опций OTLP по транспортам — в разделе Опции OTLP-экспортёра по транспортам.

Конструктор

Конструктор без параметров. При создании все поля инициализируются пустыми строками, Insecure = Ложь.

bsl

Новый ОтелНастройкиTls()

Свойства

Свойство	Тип	По умолчанию	Описание
`ФайлСертификата`	Строка	`""`	Путь к файлу корневого сертификата (CA / trust chain)
`ФайлКлиентскогоКлюча`	Строка	`""`	Путь к файлу клиентского приватного ключа (для mTLS)
`ФайлКлиентскогоСертификата`	Строка	`""`	Путь к файлу клиентского сертификата (для mTLS)
`Insecure`	Булево	`Ложь`	Только gRPC: если `Истина` — соединение с адресом без схемы идёт без TLS. Схема `http://` или `https://` адреса важнее

Методы

Применен

Проверяет, применены ли какие-либо TLS-настройки.

Возвращает: Булево — Истина, если хотя бы одно поле задано (не пустая строка или Insecure = Истина)

Пример

bsl

#Использовать opentelemetry

// gRPC без TLS для адреса без схемы (например, коллектор в той же сети)
НастройкиTls = Новый ОтелНастройкиTls();
НастройкиTls.Insecure = Истина;
Транспорт = Новый ОтелGrpcТранспорт("otel-collector:4317", НастройкиTls);

// С указанием CA-сертификата
НастройкиTls = Новый ОтелНастройкиTls();
НастройкиTls.ФайлСертификата = "/etc/ssl/certs/ca-bundle.crt";

// mTLS: поля принимаются, но пока не применяются транспортами (см. примечание)
НастройкиTls = Новый ОтелНастройкиTls();
НастройкиTls.ФайлСертификата = "/etc/ssl/ca.crt";
НастройкиTls.ФайлКлиентскогоКлюча = "/etc/ssl/client.key";
НастройкиTls.ФайлКлиентскогоСертификата = "/etc/ssl/client.crt";

// Передать в транспорт
Транспорт = Новый ОтелGrpcТранспорт("https://collector.example.com", НастройкиTls);

// Проверить, заданы ли настройки
Если НастройкиTls.Применен() Тогда
    Сообщить("TLS настроен");
КонецЕсли;

ОтелЭкспортерЛогов

Экспортер записей логов в формате OTLP.

Описание

Реализует экспорт логов по спецификации OpenTelemetry (OtlpLogExporter). Отправляет записи логов на адрес /v1/logs через любой транспорт: ОтелHttpТранспорт, ОтелGrpcТранспорт, ОтелКонсольныйТранспорт или ОтелВПамятьТранспорт.

Scope и resource читаются из каждой записи при формировании пакета OTLP. Все методы безопасны для конкурентного вызова: признак закрытия хранится в АтомарноеБулево. Экспорт идёт в вызывающем потоке и ограничен сроком: транспорт получает время, оставшееся до срока, и укладывает в него все попытки отправки и паузы между ними.

Конструктор

bsl

Новый ОтелЭкспортерЛогов(Транспорт, ПутьСигнала, ТаймаутМс, НовыйЗакрыватьТранспорт)

Параметр	Тип	По умолчанию	Описание
`Транспорт`	ОтелHttpТранспорт, ОтелGrpcТранспорт, ОтелКонсольныйТранспорт, ОтелВПамятьТранспорт	—	Транспорт для отправки данных
`ПутьСигнала`	Строка	`"/v1/logs"`	Путь OTLP-адреса для отправки логов
`ТаймаутМс`	Число	`10000`	Таймаут экспорта в миллисекундах (OTLP Timeout), `0` — без ограничения
`НовыйЗакрыватьТранспорт`	Булево	`Ложь`	`Истина` — транспорт создала библиотека (автоконфигурация, файл конфигурации), экспортер закрывает его вместе с собой. `Ложь` — транспорт передал пользователь и закрывает его сам: один транспорт может обслуживать несколько экспортеров

Методы

Экспортировать

Экспортирует массив записей логов в пределах срока. По спецификации OTel Export() не должен блокироваться бесконечно: срок экспорта — меньший из таймаута вызова и таймаута экспортера (незаданный или 0 таймаут не ограничивает). Отправка идёт в вызывающем потоке, транспорт получает время, оставшееся до срока.

Параметр	Тип	По умолчанию	Описание
`МассивЗаписей`	Массив из ОтелЗаписьЛога	—	Записи логов для экспорта
`Таймаут`	Число	`Неопределено`	Таймаут вызова в миллисекундах; `Неопределено` или `0` — действует только таймаут экспортера

Возвращает: Булево — Истина, если экспорт успешен; Ложь при ошибке или по истечении срока

СброситьБуфер

Принудительно отправляет все накопленные данные. Для синхронного экспортера операция не требуется — всегда возвращает успех.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	Число	`0`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЭкспорта — результат операции

Закрыть

Завершает работу экспортера. После вызова метод Экспортировать() возвращает Ложь. Если транспорт создала библиотека (НовыйЗакрыватьТранспорт), первый вызов закрывает и транспорт. Операция идемпотентна: повторные вызовы ничего не делают.

Возвращает: ОтелРезультатЗакрытия — результат закрытия; ошибка, если не удалось закрыть транспорт

Пример

bsl

#Использовать opentelemetry

// Создать экспортер с HTTP-транспортом
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерЛогов(Транспорт);

// С gRPC
Транспорт = Новый ОтелGrpcТранспорт("http://localhost:4317");
Экспортер = Новый ОтелЭкспортерЛогов(Транспорт);

// Интеграция с logos через аппендер
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерЛогов(Транспорт);
// Используется совместно с ОтелАппендерLogos для автоматической отправки логов

// Закрыть после использования
Экспортер.Закрыть();

ОтелЭкспортерМетрик

Экспортер метрик в формате OTLP.

Описание

Реализует экспорт метрик по спецификации OpenTelemetry (OtlpMetricExporter). Отправляет данные метрик на адрес /v1/metrics через любой транспорт: ОтелHttpТранспорт, ОтелGrpcТранспорт, ОтелКонсольныйТранспорт или ОтелВПамятьТранспорт.

Поддерживает типы метрик: Сумма, Датчик, Гистограмма, ЭкспоненциальнаяГистограмма и Сводка (Summary от продюсеров метрик; у датчика и сводки временной агрегации нет). Перед отправкой выполняет валидацию совместимости агрегаций и темпоральности. Метаданные метрики (ОтелДанныеМетрики.Метаданные()) передаются в поле metadata.

Все методы безопасны для конкурентного вызова. Поля состояния либо иммутабельны (назначаются в конструкторе), либо хранятся в АтомарноеБулево. Экспорт идёт в вызывающем потоке и ограничен сроком: транспорт получает время, оставшееся до срока, и укладывает в него все попытки отправки и паузы между ними.

Конструктор

bsl

Новый ОтелЭкспортерМетрик(
    Транспорт,
    СелекторВременнойАгрегации,
    ПутьСигнала,
    ТаймаутМс,
    АгрегацияГистограммПоУмолчанию,
    НовыйЗакрыватьТранспорт
)

Параметр	Тип	По умолчанию	Описание
`Транспорт`	ОтелHttpТранспорт, ОтелGrpcТранспорт, ОтелКонсольныйТранспорт, ОтелВПамятьТранспорт	—	Транспорт для отправки данных
`СелекторВременнойАгрегации`	УниФункция	`Неопределено`	Функция-селектор: `Применить(ТипИнструмента) → Число`; определяет временну́ю агрегацию для каждого типа инструмента. Готовые селекторы — ОтелСелекторВременнойАгрегации
`ПутьСигнала`	Строка	`"/v1/metrics"`	Путь OTLP-адреса для отправки метрик
`ТаймаутМс`	Число	`10000`	Таймаут экспорта в миллисекундах (OTLP Timeout), `0` — без ограничения
`АгрегацияГистограммПоУмолчанию`	Строка, Соответствие	`"explicit_bucket_histogram"`	Агрегация гистограмм по умолчанию (`OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION`); читатель метрик берёт её у экспортера
`НовыйЗакрыватьТранспорт`	Булево	`Ложь`	`Истина` — транспорт создала библиотека (автоконфигурация, файл конфигурации), экспортер закрывает его вместе с собой. `Ложь` — транспорт передал пользователь и закрывает его сам: один транспорт может обслуживать несколько экспортеров

Методы

Экспортировать

Экспортирует данные метрик. Перед отправкой валидирует совместимость типов метрик и темпоральности: данные неподдерживаемого типа или без временной агрегации (AggregationTemporality) не экспортируются — метод пишет предупреждение и возвращает Ложь. По спецификации OTel Export() не должен блокироваться бесконечно: срок экспорта — меньший из таймаута вызова и таймаута экспортера (незаданный или 0 таймаут не ограничивает). Отправка идёт в вызывающем потоке, транспорт получает время, оставшееся до срока.

Параметр	Тип	По умолчанию	Описание
`МассивДанныхМетрик`	Массив из ОтелДанныеМетрики	—	Данные метрик для экспорта
`Таймаут`	Число	`Неопределено`	Таймаут вызова в миллисекундах; `Неопределено` или `0` — действует только таймаут экспортера

Возвращает: Булево — Истина, если экспорт успешен; Ложь при ошибке или по истечении срока

СброситьБуфер

Принудительно отправляет все накопленные данные. Для синхронного экспортера буферизация отсутствует — всегда возвращает успех. Операция тривиально потокобезопасна (no-op).

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	Число	`0`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЭкспорта — результат операции

Закрыть

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	Число	`30000`	Таймаут операции в миллисекундах

Возвращает: ОтелРезультатЗакрытия — результат закрытия; ошибка, если не удалось закрыть транспорт

ПринудительноВыгрузитьСРезультатом

Принудительно выгружает накопленные данные и возвращает результат. Для синхронного экспортера буферизация отсутствует — операция всегда успешна, если экспортер не закрыт.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	Число	`30000`	Таймаут операции в миллисекундах

Возвращает: ОтелРезультатЗакрытия — результат операции

ПолучитьВременнуюАгрегацию

Возвращает временну́ю агрегацию для указанного типа инструмента.

Параметр	Тип	По умолчанию	Описание
`ТипИнструмента`	Строка	—	Тип инструмента: `"counter"`, `"up_down_counter"`, `"histogram"`, `"gauge"` и т.д.

Возвращает: Число — значение из ОтелВременнаяАгрегация

АгрегацияПоУмолчанию

Возвращает агрегацию по умолчанию для вида инструмента: читатель метрик берёт её у экспортера. Гистограммам — агрегация гистограмм экспортера, остальным видам — агрегация по умолчанию.

Параметр	Тип	По умолчанию	Описание
`ВидИнструмента`	Строка	—	Вид инструмента: `"Counter"`, `"Histogram"`, `"Gauge"` и т.д.

Возвращает: Строка, Соответствие — агрегация; "default" — агрегация по умолчанию для вида

Пример

bsl

#Использовать opentelemetry

// Создать экспортер с HTTP-транспортом
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерМетрик(Транспорт);

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

// Закрыть после использования
Экспортер.Закрыть();

ОтелЭкспортерСпанов

Экспортер завершённых спанов трассировки в формате OTLP.

Описание

Реализует экспорт спанов по спецификации OpenTelemetry (OtlpSpanExporter). Отправляет завершённые спаны на адрес /v1/traces через любой транспорт: ОтелHttpТранспорт, ОтелGrpcТранспорт, ОтелКонсольныйТранспорт или ОтелВПамятьТранспорт.

Все методы (Экспортировать, СброситьБуфер, Закрыть) безопасны для конкурентного вызова: признак закрытия хранится в АтомарноеБулево. Экспорт идёт в вызывающем потоке и ограничен сроком: транспорт получает время, оставшееся до срока, и укладывает в него все попытки отправки и паузы между ними.

Конструктор

bsl

Новый ОтелЭкспортерСпанов(Транспорт, ПутьСигнала, ТаймаутМс, НовыйЗакрыватьТранспорт)

Параметр	Тип	По умолчанию	Описание
`Транспорт`	ОтелHttpТранспорт, ОтелGrpcТранспорт, ОтелКонсольныйТранспорт, ОтелВПамятьТранспорт	—	Транспорт для отправки данных
`ПутьСигнала`	Строка	`"/v1/traces"`	Путь OTLP-адреса для отправки спанов
`ТаймаутМс`	Число	`10000`	Таймаут экспорта в миллисекундах (OTLP Timeout), `0` — без ограничения
`НовыйЗакрыватьТранспорт`	Булево	`Ложь`	`Истина` — транспорт создала библиотека (автоконфигурация, файл конфигурации), экспортер закрывает его вместе с собой. `Ложь` — транспорт передал пользователь и закрывает его сам: один транспорт может обслуживать несколько экспортеров

Методы

Экспортировать

Экспортирует массив завершённых спанов в пределах срока. По спецификации OTel Export() не должен блокироваться бесконечно: срок экспорта — меньший из таймаута вызова и таймаута экспортера (незаданный или 0 таймаут не ограничивает). Отправка идёт в вызывающем потоке, транспорт получает время, оставшееся до срока.

Параметр	Тип	По умолчанию	Описание
`МассивСпанов`	Массив из ОтелСпан	—	Спаны для экспорта
`Таймаут`	Число	`Неопределено`	Таймаут вызова в миллисекундах; `Неопределено` или `0` — действует только таймаут экспортера

Возвращает: Булево — Истина, если экспорт успешен; Ложь при ошибке или по истечении срока

СброситьБуфер

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	Число	`0`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЭкспорта — результат операции

Закрыть

Возвращает: ОтелРезультатЗакрытия — результат закрытия; ошибка, если не удалось закрыть транспорт

Пример

bsl

#Использовать opentelemetry

// Создать экспортер с HTTP-транспортом
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерСпанов(Транспорт);

// С gRPC
Транспорт = Новый ОтелGrpcТранспорт("http://localhost:4317");
Экспортер = Новый ОтелЭкспортерСпанов(Транспорт);

// Для тестирования — в памяти
ТестТранспорт = Новый ОтелВПамятьТранспорт();
Экспортер = Новый ОтелЭкспортерСпанов(ТестТранспорт);

// Закрыть после использования. Транспорт создан пользователем: его закрывает пользователь
Экспортер.Закрыть();
ТестТранспорт.Закрыть();

ИнтерфейсДетекторРесурса

Интерфейс детектора ресурса (Resource Detector): контракт встроенных и своих детекторов.

Описание

Детектор определяет атрибуты среды, в которой работает приложение, и возвращает их ресурсом ОтелРесурс. Встроенные детекторы — хоста, процесса, процессора, контейнера и экземпляра сервиса — сливает ОтелРесурсы.ИзДетекторов. Свой детектор пишут для атрибутов, которых нет у встроенных: например, региона облака или версии приложения из файла сборки. Аналог Java SDK: ResourceProvider.

Интерфейс — класс ИнтерфейсДетекторРесурса с аннотацией &Интерфейс библиотеки extends. Детектор объявляет реализацию аннотацией &Реализует("ИнтерфейсДетекторРесурса") у конструктора ПриСозданииОбъекта. Аннотация обязательна: ОтелРесурсы.ИзДетекторов перед вызовом Обнаружить() проверяет каждый детектор методом РеализуетИнтерфейс объекта ВалидаторРеализации библиотеки extends и выбрасывает исключение, если детектор не объявляет интерфейс или не реализует его методы.

Настройки детектору передают при создании, параметрами конструктора: Обнаружить() параметров не принимает.

Методы

Обнаружить

Возвращает ресурс, обнаруженный детектором. Детектор, которому нечего сообщить, возвращает пустой ресурс. Адрес схемы ресурса — пустой или версия семантических соглашений атрибутов детектора, например https://opentelemetry.io/schemas/1.44.0, как у встроенных детекторов. При слиянии ресурсов с разными непустыми адресами схемы адрес схемы результата пустой, а ошибка пишется в лог.

Исключение в Обнаружить() или результат не ОтелРесурс не прерывают сбор ресурса: ОтелРесурсы.ИзДетекторов пишет ошибку в лог oscript.lib.opentelemetry.resource и пропускает детектор. Так требуют принципы обработки ошибок спецификации: ошибка обнаружения — ошибка, но SDK не должен останавливать приложение из-за телеметрии.

Возвращает: ОтелРесурс — обнаруженный ресурс

Пример

Детектор региона приложения — класс приложения в файле ДетекторРегиона.os:

bsl

Перем Регион;

Функция Обнаружить() Экспорт
    Атрибуты = Новый Соответствие();
    Атрибуты.Вставить("cloud.region", Регион);
    Возврат Новый ОтелРесурс(Атрибуты);
КонецФункции

&Реализует("ИнтерфейсДетекторРесурса")
Процедура ПриСозданииОбъекта(НовыйРегион)
    Регион = НовыйРегион;
КонецПроцедуры

Детектор в автоконфигурации — сливается после встроенных детекторов, атрибуты из конфигурации его перекрывают:

bsl

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "ДетекторРегиона.os"), "ДетекторРегиона");

Детекторы = Новый Массив;
Детекторы.Добавить(Новый ДетекторРегиона("eu-central-1"));

Сдк = ОтелАвтоконфигурация.Инициализировать(, Детекторы);

Ресурс для провайдеров, собранных вручную, — ресурс по умолчанию, встроенные детекторы и свой детектор:

bsl

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "ДетекторРегиона.os"), "ДетекторРегиона");

Детекторы = Новый Массив;
Детекторы.Добавить(Новый ДетекторРегиона("eu-central-1"));

Ресурс = ОтелРесурсы.ПоУмолчанию()
    .Слить(ОтелРесурсы.ИзДетекторов())
    .Слить(ОтелРесурсы.ИзДетекторов(Детекторы));

Провайдер = Новый ОтелПровайдерТрассировки(Ресурс);

См. также

ОтелBaggage

Класс Baggage по спецификации W3C Baggage.

Описание

Хранит пары ключ-значение для передачи контекстных данных между сервисами. ОтелBaggage иммутабелен — внутри хранит ФиксированноеСоответствие. Для создания или изменения используйте ОтелПостроительBaggage или метод ТоПостроитель().

Аналог Java SDK: Baggage.

Конструктор

Параметр	Тип	По умолчанию	Описание
`НовыеЗначения`	`Соответствие`	`Неопределено`	Пары ключ-значение
`НовыеМетаданные`	`Соответствие`	`Неопределено`	Метаданные по ключам

Обычно создаётся через ОтелПостроительBaggage.Построить().

Методы

Текущий

Возвращает текущий Baggage из контекста выполнения. Аналог Java SDK: Baggage.current().

Возвращает: ОтелBaggage, Неопределено — текущий Baggage или Неопределено

СделатьТекущим

Делает этот Baggage текущим в контексте выполнения.

Возвращает: ОтелТокенКонтекста — токен; передайте в ОтелКонтекст.ОтсоединитьКонтекст() или вызовите Закрыть()

Получить

Возвращает значение по ключу.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ записи

Возвращает: Строка, Неопределено — значение или Неопределено, если ключ не найден

ПолучитьМетаданные

Возвращает метаданные по ключу.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ записи

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

Установить

Возвращает новый Baggage с добавленной парой ключ-значение.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ
`Значение`	`Строка`	—	Значение

Возвращает: ОтелBaggage — новый иммутабельный экземпляр с добавленным значением

Удалить

Возвращает новый Baggage без указанного ключа.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ для удаления

Возвращает: ОтелBaggage — новый иммутабельный экземпляр без указанного ключа

Очистить

Возвращает новый пустой Baggage.

Возвращает: ОтелBaggage — новый пустой иммутабельный экземпляр

ПолучитьВсе

Возвращает все пары ключ-значение.

Возвращает: ФиксированноеСоответствие — иммутабельная коллекция

ТоПостроитель

Создает построитель на основе текущего Baggage. Аналог Java SDK: Baggage.toBuilder().

Возвращает: ОтелПостроительBaggage

Количество

Возвращает количество записей.

Возвращает: Число

ПолучитьВсеМетаданные

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

Возвращает: ФиксированноеСоответствие — иммутабельная коллекция метаданных

Пример

bsl

Baggage = Новый ОтелПостроительBaggage()
    .Установить("userId", "12345")
    .Установить("tenantId", "abc")
    .Построить();

Токен = Baggage.СделатьТекущим();
// ... работа в контексте Baggage ...
Токен.Закрыть();

См. также

ОтелSdk

Главный класс OpenTelemetry SDK — единая точка входа в телеметрию.

Описание

Агрегирует ОтелПровайдерТрассировки, ОтелПровайдерЛогирования, ОтелПровайдерМетрик и пропагаторы контекста. Предоставляет shortcut-методы для получения ОтелТрассировщик, ОтелЛоггер и ОтелМетр.

Аналог Java SDK: OpenTelemetrySdk.

Экземпляр создаётся через ОтелПостроительSdk — прямой вызов конструктора в пользовательском коде не рекомендуется.

Не заданный провайдер заменяется no-op провайдером, не заданные пропагаторы — ОтелНоопПропагатор (как в Java OpenTelemetrySdkBuilder). Поэтому shortcut-методы всегда возвращают рабочие объекты: например, у SDK из файла конфигурации без секции tracer_providerПолучитьТрассировщик() возвращает трассировщик, который создаёт незаписывающие спаны. Логгеры no-op провайдера выключены, инструменты его метров не хранят измерений.

Конструктор

Параметр	Тип	По умолчанию	Описание
`ПровайдерТрассировки`	`ОтелПровайдерТрассировки`	`Неопределено`	Провайдер трассировки; не задан — no-op провайдер
`ПровайдерЛогирования`	`ОтелПровайдерЛогирования`	`Неопределено`	Провайдер логирования; не задан — no-op провайдер
`ПровайдерМетрик`	`ОтелПровайдерМетрик`	`Неопределено`	Провайдер метрик; не задан — no-op провайдер
`Пропагаторы`	`ОтелКомпозитныйПропагатор`	`Неопределено`	Пропагаторы контекста; не заданы — `ОтелНоопПропагатор`
`НовыйТаймаутЗакрытияМс`	`Число`	`30000`	Таймаут `Закрыть` без параметра в миллисекундах, `0` — без ограничения

Методы

ПровайдерТрассировки

Возвращает провайдер трассировки.

Возвращает: ОтелПровайдерТрассировки — провайдер трассировки

ПровайдерЛогирования

Возвращает провайдер логирования.

Возвращает: ОтелПровайдерЛогирования — провайдер логирования

ПровайдерМетрик

Возвращает провайдер метрик.

Возвращает: ОтелПровайдерМетрик — провайдер метрик

Пропагаторы

Возвращает пропагаторы контекста.

Возвращает: ОтелКомпозитныйПропагатор, ОтелНоопПропагатор — пропагаторы контекста; ОтелНоопПропагатор, если они не заданы

ПолучитьТрассировщик

Shortcut: получить трассировщик. Аналог Java SDK: openTelemetry.getTracer("name").

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки

Возвращает: ОтелТрассировщик — трассировщик

ПостроительТрассировщика

Shortcut: получить построитель трассировщика.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки

Возвращает: ОтелПостроительТрассировщика — построитель трассировщика

ПолучитьЛоггер

Shortcut: получить логгер.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки

Возвращает: ОтелЛоггер — логгер

ПостроительЛоггера

Shortcut: получить построитель логгера.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки

Возвращает: ОтелПостроительЛоггера — построитель логгера

ПолучитьМетр

Shortcut: получить метр.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки

Возвращает: ОтелМетр — метр

ПостроительМетра

Shortcut: получить построитель метра.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки

Возвращает: ОтелПостроительМетра — построитель метра

СброситьБуфер

Принудительно отправляет все накопленные данные из всех провайдеров.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут в миллисекундах (0 — без ограничения)

Возвращает: ОтелРезультатЭкспорта — агрегированный результат сброса всех провайдеров

ТаймаутЗакрытия

Возвращает таймаут, с которым SDK закрывается, если Закрыть вызван без таймаута. Задаётся построителем (УстановитьТаймаутЗакрытия), при автоконфигурации — переменной OTEL_SDK_SHUTDOWN_TIMEOUT.

Возвращает: Число — таймаут в миллисекундах (0 — без ограничения)

Закрыть

Завершает работу всех провайдеров.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`Неопределено`	Таймаут завершения в миллисекундах, `0` — без ограничения. Если не задан, действует `ТаймаутЗакрытия()`

Возвращает: ОтелРезультатЗакрытия — первый неуспешный результат или успешный результат

Пример

bsl

Сдк = Новый ОтелПостроительSdk()
    .УстановитьПровайдерТрассировки(ПровайдерТрассировки)
    .УстановитьПровайдерМетрик(ПровайдерМетрик)
    .Построить();

Трассировщик = Сдк.ПолучитьТрассировщик("мой-сервис");
Спан = Трассировщик.НачатьСпан("обработка-запроса");
// ...
Спан.Завершить();

Сдк.Закрыть();

См. также

ОтелАтрибуты

Класс для хранения атрибутов (пар ключ-значение) телеметрии OpenTelemetry.

Описание

Атрибуты используются для описания ресурсов, спанов, событий, записей логов и точек данных метрик. Внутри хранит обычное Соответствие. Поддерживает цепочку вызовов (fluent API) через метод Установить.

Методы

Установить

Устанавливает значение атрибута по ключу.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Имя атрибута
`Значение`	`Произвольный`	—	Значение атрибута: строка, число, булево, массив, соответствие или структура, двоичные данные, `Неопределено`. Значение другого типа экспортируется строкой (`Строка(Значение)`)

Возвращает: ОтелАтрибуты — ссылка на текущий объект для цепочки вызовов

Получить

Возвращает значение атрибута по ключу.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Имя атрибута

Возвращает: Произвольный — значение атрибута или Неопределено

Удалить

Удаляет атрибут по ключу.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Имя атрибута

Количество

Возвращает количество атрибутов.

Возвращает: Число — количество атрибутов

ВСоответствие

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

Возвращает: Соответствие — внутреннее соответствие атрибутов

ВМассивOtlp

Преобразует атрибуты в массив формата OTLP JSON.

Возвращает: Массив — массив объектов {"key": "...", "value": {...}}

Ключ

Возвращает ключ набора атрибутов для сравнения и группировки. Одинаковые наборы дают одинаковый ключ независимо от порядка добавления, разные — разный. Значение учитывается вместе с типом: строка "1" и число 1 дают разные ключи.

Возвращает: Строка — ключ набора (пустая строка для пустого набора)

Пример

bsl

Атрибуты = Новый ОтелАтрибуты()
    .Установить("http.method", "GET")
    .Установить("http.status_code", 200)
    .Установить("http.url", "https://example.com/api");

Значение = Атрибуты.Получить("http.method"); // "GET"

См. также

ОтелГлобальный

Модуль глобального реестра OpenTelemetry (GlobalOpenTelemetry).

Описание

Хранит единственный экземпляр ОтелSdk для всего приложения. Потокобезопасен: использует АтомарнаяСсылка. Аналог Java SDK: GlobalOpenTelemetry.

Если SDK не установлен явно, shortcut-методы используют noop-fallback (SDK с AlwaysOff семплером, без процессоров и читателей), чтобы инструментирующий код не блокировал конфигурацию. Его провайдер метрик выдаёт no-op метры: инструменты выключены и не хранят измерений.

Глобальные провайдеры трассировки, логирования и метрик (global default TracerProvider, LoggerProvider, MeterProvider) устанавливаются и читаются и без SDK — так же, как пропагаторы. Порядок выбора: провайдер, установленный методом УстановитьПровайдер..., затем провайдер зарегистрированного SDK, затем no-op провайдер. Shortcut-методы ПолучитьТрассировщик, ПолучитьЛоггер и ПолучитьМетр берут объекты из этих провайдеров.

Функции

Установить

Устанавливает глобальный экземпляр OpenTelemetry SDK. Может быть вызван только один раз; повторный вызов вызывает исключение. Потокобезопасен (CAS).

Параметр	Тип	По умолчанию	Описание
`Сдк`	`ОтелSdk`	—	Экземпляр SDK

Получить

Возвращает глобальный экземпляр OpenTelemetry SDK.

Возвращает: ОтелSdk, Неопределено

Сбросить

Сбрасывает глобальный экземпляр, пропагаторы и явно установленные провайдеры. Предназначен для тестов.

СброситьИЗакрыть

Закрывает SDK и сбрасывает глобальный экземпляр. Явно установленные провайдеры сбрасываются без закрытия: ими владеет вызывающий код. Предназначен для тестов.

УстановитьПровайдерТрассировки / УстановитьПровайдерЛогирования / УстановитьПровайдерМетрик

Устанавливают глобальный провайдер сигнала. Могут использоваться независимо от SDK: установленный провайдер важнее провайдера зарегистрированного SDK.

Параметр	Тип	По умолчанию	Описание
`Провайдер`	`ОтелПровайдерТрассировки`, `ОтелПровайдерЛогирования`, `ОтелПровайдерМетрик`	—	Провайдер сигнала

ПолучитьПровайдерТрассировки / ПолучитьПровайдерЛогирования / ПолучитьПровайдерМетрик

Возвращают глобальный провайдер сигнала: установленный явно, иначе провайдер зарегистрированного SDK, иначе no-op провайдер. Никогда не возвращают Неопределено. Через провайдер доступны все параметры получения трассировщика, логгера и метра (атрибуты области, адрес схемы).

Возвращает: ОтелПровайдерТрассировки, ОтелПровайдерЛогирования, ОтелПровайдерМетрик

ПолучитьТрассировщик

Shortcut: получить трассировщик из глобального провайдера трассировки.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки

Возвращает: ОтелТрассировщик

ПолучитьЛоггер

Shortcut: получить логгер из глобального провайдера логирования.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки

Возвращает: ОтелЛоггер

ПолучитьМетр

Shortcut: получить метр из глобального провайдера метрик.

Параметр	Тип	По умолчанию	Описание
`ИмяБиблиотеки`	`Строка`	—	Имя инструментирующей библиотеки
`ВерсияБиблиотеки`	`Строка`	`""`	Версия библиотеки

Возвращает: ОтелМетр

УстановитьПропагаторы

Устанавливает глобальные пропагаторы контекста. Может использоваться независимо от SDK.

Параметр	Тип	По умолчанию	Описание
`Пропагаторы`	`ОтелКомпозитныйПропагатор`, `ОтелНоопПропагатор`	—	Пропагаторы контекста

ПолучитьПропагаторы

Возвращает глобальные пропагаторы контекста. Если не установлены явно — из SDK. Если пропагаторы не настроены ни явно, ни в SDK — ОтелНоопПропагатор: по спецификации API использует no-op пропагаторы, пока они не настроены. ОтелАвтоконфигурация.Инициализировать() настраивает W3C Trace Context и W3C Baggage (OTEL_PROPAGATORS по умолчанию tracecontext,baggage); SDK, собранный через ОтелПостроительSdk, получает пропагаторы через УстановитьПропагаторы.

Возвращает: ОтелКомпозитныйПропагатор, ОтелНоопПропагатор — пропагаторы контекста

Пример

bsl

// Регистрация
ОтелГлобальный.Установить(Сдк);

// Использование из любой точки приложения
Трассировщик = ОтелГлобальный.ПолучитьТрассировщик("мой-сервис");
Спан = Трассировщик.НачатьСпан("операция");
// ...
Спан.Завершить();

// Глобальный провайдер метрик без SDK и метр с адресом схемы
ОтелГлобальный.УстановитьПровайдерМетрик(ПровайдерМетрик);
Метр = ОтелГлобальный.ПолучитьПровайдерМетрик()
    .ПолучитьМетр("мой-сервис", "1.0.0", , "https://opentelemetry.io/schemas/1.26.0");

См. также

ОтелДетекторРесурсаКонтейнера

Детектор ресурса контейнера: идентификатор контейнера, в котором запущен процесс.

Описание

Этот детектор вызывает ОтелРесурсы.ИзДетекторов, через неё атрибуты попадают в ресурс автоконфигурации и файловой конфигурации. Самому вызывать детектор нужно, только чтобы получить эти атрибуты отдельно.

Атрибут	Значение
`container.id`	Идентификатор контейнера из 64 шестнадцатеричных символов

Идентификатор определяется только на Linux:

из /proc/self/cgroup — последний сегмент пути cgroup из 64 шестнадцатеричных символов, в том числе с префиксом среды (docker-, cri-containerd-, crio-, libpod-) и суффиксом .scope; так идентификатор виден при cgroup v1 и при cgroup v2 без собственного пространства имён;
если в cgroup его нет — из /proc/self/mountinfo: каталог контейнера Docker (containers/<id>) или podman (containers/overlay-containers/<id>) в точках монтирования; так идентификатор виден при cgroup v2 с собственным пространством имён. Каталог песочницы pod-а Kubernetes (sandboxes/<id>) не берётся: это идентификатор pod-а, а не контейнера.

На Windows и macOS идентификатор контейнера изнутри процесса не определить, детектор возвращает пустой ресурс. Процесс вне контейнера тоже получает пустой ресурс.

Атрибуты образа контейнера (container.image.name, container.image.tags, container.image.repo_digests) детектор не заполняет: изнутри процесса их не узнать, они есть только у среды исполнения контейнеров (Docker API, API Kubernetes). Строковый container.image.name можно задать в OTEL_RESOURCE_ATTRIBUTES (container.image.name=registry.example.com/my-app). container.image.tags и container.image.repo_digests — массивы строк, а OTEL_RESOURCE_ATTRIBUTES задаёт только строки: их задают в resource.attributes файловой конфигурации с типом string_array.

В Kubernetes атрибуты образа может добавить коллектор, процессор k8sattributes, но не по умолчанию: нужные атрибуты перечисляются в его extract.metadata, а контейнер pod-а процессор находит по container.id (его заполняет этот детектор) или k8s.container.name. container.image.repo_digests процессор добавляет, только если дайджест образа передаёт среда исполнения контейнеров (CRI).

Если файл прочитать не удалось, детектор пишет ошибку в лог oscript.lib.opentelemetry.resource.container и возвращает пустой ресурс. Исключение он не выбрасывает.

Конструктор

bsl

Новый ОтелДетекторРесурсаКонтейнера(Cgroup, Mountinfo, ТипОС)

Параметр	Тип	По умолчанию	Описание
`Cgroup`	`Строка`	`/proc/self/cgroup`	Путь к файлу cgroup процесса
`Mountinfo`	`Строка`	`/proc/self/mountinfo`	Путь к файлу mountinfo процесса
`ТипОС`	`Строка`	ОС текущей машины	Тип ОС в значениях `os.type`: `linux`, `windows`, `darwin`. Идентификатор ищется только при `linux`

Параметры нужны для тестов; в обычной работе детектор создаётся без параметров.

Методы

Обнаружить

Определяет идентификатор контейнера.

Возвращает: ОтелРесурс — ресурс без атрибутов по умолчанию: только container.id и адрес схемы https://opentelemetry.io/schemas/1.44.0. Если процесс не в контейнере или идентификатор не определён — пустой ресурс без адреса схемы

Пример

bsl

РесурсКонтейнера = Новый ОтелДетекторРесурсаКонтейнера().Обнаружить();
ИдКонтейнера = РесурсКонтейнера.Атрибуты().Получить("container.id");

См. также

ОтелРесурс

ОтелДетекторРесурсаПроцесса

Детектор ресурса процесса: идентификатор текущего процесса.

Описание

Атрибут	Значение
`process.pid`	Идентификатор процесса (`ТекущийПроцесс().Идентификатор`)

Если идентификатор получить не удалось, детектор пишет ошибку в лог oscript.lib.opentelemetry.resource.process и возвращает пустой ресурс. Исключение он не выбрасывает.

Конструктор

bsl

Новый ОтелДетекторРесурсаПроцесса()

Без параметров.

Методы

Обнаружить

Определяет атрибуты процесса.

Возвращает: ОтелРесурс — ресурс без атрибутов по умолчанию: только process.pid и адрес схемы https://opentelemetry.io/schemas/1.44.0. Если идентификатор не определён — пустой ресурс без адреса схемы

Пример

bsl

РесурсПроцесса = Новый ОтелДетекторРесурсаПроцесса().Обнаружить();
ИдПроцесса = РесурсПроцесса.Атрибуты().Получить("process.pid");

См. также

ОтелДетекторРесурсаПроцессора

Детектор ресурса процессора: модель и архитектура процессора.

Описание

Сведения о процессоре определяет библиотека cpuinfo (ИнформацияОПроцессоре) при каждом вызове Обнаружить(), если они не переданы в конструктор. Атрибут, который cpuinfo не определил (например, на неподдерживаемой платформе), в ресурс не попадает.

Атрибут	Значение
`host.cpu.model.name`	Имя процессора
`host.arch`	`amd64`, `x86`, `arm64` или `arm32`; другая архитектура — её имя из cpuinfo в нижнем регистре

Если сведения получить не удалось, детектор пишет ошибку в лог oscript.lib.opentelemetry.resource.cpu и возвращает ресурс без недоступных атрибутов. Исключение он не выбрасывает.

Конструктор

bsl

Новый ОтелДетекторРесурсаПроцессора(СведенияОПроцессоре)

Параметр	Тип	По умолчанию	Описание
`СведенияОПроцессоре`	`ИнформацияОПроцессоре`	`Неопределено`	Готовые сведения о процессоре из cpuinfo; `Неопределено` — cpuinfo определяет их при каждом вызове `Обнаружить()`

Методы

Обнаружить

Определяет атрибуты процессора.

Возвращает: ОтелРесурс — ресурс без атрибутов по умолчанию: только атрибуты процессора и адрес схемы https://opentelemetry.io/schemas/1.44.0. Если ни один атрибут не определён — пустой ресурс без адреса схемы

Пример

bsl

РесурсПроцессора = Новый ОтелДетекторРесурсаПроцессора().Обнаружить();
Архитектура = РесурсПроцессора.Атрибуты().Получить("host.arch"); // например, "amd64"

См. также

ОтелДетекторРесурсаХоста

Детектор ресурса хоста: имя компьютера и тип операционной системы.

Описание

Атрибут	Значение
`host.name`	Имя компьютера (`СистемнаяИнформация.ИмяКомпьютера`)
`os.type`	`linux`, `windows` или `darwin` (macOS); на другой платформе — тип платформы OneScript в нижнем регистре

Если сведения получить не удалось, детектор пишет ошибку в лог oscript.lib.opentelemetry.resource.host и возвращает ресурс без недоступных атрибутов. Исключение он не выбрасывает.

Конструктор

bsl

Новый ОтелДетекторРесурсаХоста()

Без параметров.

Методы

Обнаружить

Определяет атрибуты хоста.

Возвращает: ОтелРесурс — ресурс без атрибутов по умолчанию: только атрибуты хоста и адрес схемы https://opentelemetry.io/schemas/1.44.0. Если ни один атрибут не определён — пустой ресурс без адреса схемы

Пример

bsl

РесурсХоста = Новый ОтелДетекторРесурсаХоста().Обнаружить();
ИмяХоста = РесурсХоста.Атрибуты().Получить("host.name");

См. также

ОтелДетекторРесурсаЭкземпляраСервиса

Детектор ресурса экземпляра сервиса: идентификатор экземпляра.

Описание

Этот детектор вызывает ОтелРесурсы.ИзДетекторов, через неё атрибут попадает в ресурс автоконфигурации и файловой конфигурации. Самому вызывать детектор нужно, только чтобы получить этот атрибут отдельно.

Атрибут	Значение
`service.instance.id`	Случайный UUID, один на процесс

Как и в Java SDK, идентификатор создаётся один раз на процесс: все ресурсы процесса получают одно и то же значение, а после перезапуска процесса значение новое. В ресурсе автоконфигурации и файловой конфигурации значение из OTEL_RESOURCE_ATTRIBUTES или resource файловой конфигурации заменяет сгенерированное.

Конструктор

bsl

Новый ОтелДетекторРесурсаЭкземпляраСервиса()

Без параметров.

Методы

Обнаружить

Определяет атрибут экземпляра сервиса.

Возвращает: ОтелРесурс — ресурс без атрибутов по умолчанию: только service.instance.id и адрес схемы https://opentelemetry.io/schemas/1.44.0

Пример

bsl

РесурсЭкземпляра = Новый ОтелДетекторРесурсаЭкземпляраСервиса().Обнаружить();
ИдЭкземпляра = РесурсЭкземпляра.Атрибуты().Получить("service.instance.id");

См. также

ОтелРесурс

ОтелКлючКонтекста

Ключ для хранения значений в контексте.

Описание

Ключи сравниваются по ссылке, а не по имени — два ключа с одинаковым именем являются разными ключами. Имя используется только для отладки.

Создаётся через ОтелКонтекст.СоздатьКлюч(Имя).

Конструктор

Параметр	Тип	По умолчанию	Описание
`Имя`	`Строка`	—	Имя ключа (для отладки)

Методы

Имя

Возвращает имя ключа (для отладки).

Возвращает: Строка — имя ключа

Пример

bsl

КлючСессии = ОтелКонтекст.СоздатьКлюч("session");

// Создать контекст с сессией
НовыйКонтекст = ОтелКонтекст.КонтекстСоЗначением(
    ОтелКонтекст.Текущий(),
    КлючСессии,
    СессионныйОбъект
);

// Прочитать из контекста
Сессия = ОтелКонтекст.ПолучитьИзКонтекста(ОтелКонтекст.Текущий(), КлючСессии);

См. также

ОтелКонтекст

Модуль для управления текущим контекстом выполнения.

Описание

Реализует generic key-value хранилище контекста (аналог Java SDK: io.opentelemetry.context.Context). Каждый поток исполнения имеет свой стек контекстов. Контекст — это ФиксированноеСоответствие ключ → значение. Ключи — ОтелКлючКонтекста, сравниваются по ссылке.

Стек хранится в данных потока исполнения (ТекущийПоток().Данные). Движок выделяет отдельный поток исполнения основному скрипту, каждому фоновому заданию и каждому запросу веб-сервера. Другие потоки стек не видят, поэтому синхронизация не нужна, а после завершения потока движок освобождает его данные сам.

Важно: Ключи для спана и Baggage являются приватными переменными модуля. Для работы со спанами и Baggage используйте специализированные методы ТекущийСпан(), ТекущийBaggage() и т.д.

Функции

СоздатьКлюч

Создает новый ключ контекста. Ключи сравниваются по ссылке — два ключа с одинаковым именем являются разными ключами.

Параметр	Тип	По умолчанию	Описание
`Имя`	`Строка`	—	Имя ключа (для отладки)

Возвращает: ОтелКлючКонтекста — новый ключ контекста

Текущий

Возвращает текущий контекст (верхний элемент стека). Если стек пуст, возвращает пустой иммутабельный контекст.

Возвращает: ФиксированноеСоответствие — текущий контекст (иммутабельный)

Получить

Возвращает значение из текущего контекста по ключу.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`ОтелКлючКонтекста`	—	Ключ контекста

Возвращает: Произвольный, Неопределено — значение по ключу или Неопределено

ТекущийСпан

Возвращает текущий спан из контекста текущего потока.

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

ТекущийBaggage

Возвращает текущий Baggage из контекста текущего потока.

Возвращает: ОтелBaggage, Неопределено — текущий Baggage или Неопределено

ПолучитьИзКонтекста

Возвращает значение из переданного контекста по ключу.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`	—	Контекст
`Ключ`	`ОтелКлючКонтекста`	—	Ключ контекста

Возвращает: Произвольный, Неопределено — значение по ключу или Неопределено

КонтекстСоЗначением

Создает новый иммутабельный контекст с установленным значением.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`	—	Исходный контекст
`Ключ`	`ОтелКлючКонтекста`	—	Ключ контекста
`Значение`	`Произвольный`	—	Значение для установки

Возвращает: ФиксированноеСоответствие — новый иммутабельный контекст

СпанИзКонтекста

Возвращает спан из переданного контекста или из текущего контекста потока.

Параметр	Тип	По умолчанию	Описание
`КонтекстОбъект`	`ФиксированноеСоответствие`, `Соответствие`, `Неопределено`	`Неопределено`	Явный контекст

Возвращает: ОтелСпан, Неопределено — спан или Неопределено

BaggageИзКонтекста

Возвращает Baggage из переданного контекста или из текущего контекста потока.

Параметр	Тип	По умолчанию	Описание
`КонтекстОбъект`	`ФиксированноеСоответствие`, `Соответствие`, `Неопределено`	`Неопределено`	Явный контекст

Возвращает: ОтелBaggage, Неопределено — Baggage или Неопределено

КонтекстСоСпаном

Создает новый иммутабельный контекст (копию переданного) с установленным спаном.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`	—	Исходный контекст
`Спан`	`ОтелСпан`, `ОтелНезаписывающийСпан`	—	Спан для установки; незаписывающий спан из контекста спана создаёт `ОтелСпаны.Обернуть`

Возвращает: ФиксированноеСоответствие — новый иммутабельный контекст со спаном

КонтекстСBaggage

Создает новый иммутабельный контекст (копию переданного) с установленным Baggage. Текущий контекст потока не меняется: такой контекст передают пропагатору (Внедрить) или делают текущим через ПрисоединитьКонтекст.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`	—	Исходный контекст
`Багаж`	`ОтелBaggage`	—	Baggage для установки

Возвращает: ФиксированноеСоответствие — новый иммутабельный контекст с Baggage

УстановитьЗначение

Делает текущим контекст, в котором к значениям текущего контекста добавлено значение по ключу (или заменено прежнее). Аналог Java: Context.current().with(key, value).makeCurrent(). Новый контекст помещается на вершину стека потока, как при ПрисоединитьКонтекст; предыдущий восстанавливают Закрыть() токена или ОтсоединитьКонтекст(Токен).

Параметр	Тип	По умолчанию	Описание
`Ключ`	`ОтелКлючКонтекста`	—	Ключ контекста (см. `СоздатьКлюч`)
`Значение`	`Произвольный`	—	Значение для установки

Возвращает: ОтелТокенКонтекста — токен для восстановления предыдущего контекста

СделатьСпанТекущим

Делает спан текущим: помещает на вершину стека потока копию текущего контекста с этим спаном, остальные значения контекста (например, Baggage) сохраняются. Через эту функцию работает СделатьТекущим() у ОтелСпан и ОтелНезаписывающийСпан. Завершение спана токен не закрывает: закройте его сами.

Параметр	Тип	По умолчанию	Описание
`Спан`	`ОтелСпан`, `ОтелНезаписывающийСпан`	—	Спан, который станет текущим

Возвращает: ОтелТокенКонтекста — токен для восстановления предыдущего контекста

СделатьBaggageТекущим

Делает Baggage текущим: помещает на вершину стека потока копию текущего контекста с этим Baggage, остальные значения контекста (например, текущий спан) сохраняются. Через эту функцию работает ОтелBaggage.СделатьТекущим().

Параметр	Тип	По умолчанию	Описание
`Багаж`	`ОтелBaggage`	—	Baggage, который станет текущим

Возвращает: ОтелТокенКонтекста — токен для восстановления предыдущего контекста

ПрисоединитьКонтекст

Присоединяет новый контекст к текущему потоку (Attach Context). Помещает контекст на вершину стека.

Параметр	Тип	По умолчанию	Описание
`Контекст`	`ФиксированноеСоответствие`, `Соответствие`	—	Контекст для установки

Возвращает: ОтелТокенКонтекста — токен для последующего ОтсоединитьКонтекст()

ОтсоединитьКонтекст

Отсоединяет контекст по токену, восстанавливая предыдущий (Detach Context).

Параметр	Тип	По умолчанию	Описание
`Токен`	`ОтелТокенКонтекста`	—	Токен, возвращенный из `ПрисоединитьКонтекст()`

Возвращает: Булево — Истина при корректном порядке, Ложь при нарушении

Очистить

Очищает контекст текущего потока.

Пример

bsl

// RAII-паттерн
Токен = Спан.СделатьТекущим();
Попытка
    // ... работа в контексте спана ...
Исключение
    Спан.ЗаписатьИсключение(ИнформацияОбОшибке());
КонецПопытки;
Токен.Закрыть();
Спан.Завершить();

// Явный Attach/Detach
Токен = ОтелКонтекст.ПрисоединитьКонтекст(НовыйКонтекст);
// ... работа ...
ОтелКонтекст.ОтсоединитьКонтекст(Токен);

// Своё значение в текущем контексте
КлючЗапроса = ОтелКонтекст.СоздатьКлюч("request.id");
Токен = ОтелКонтекст.УстановитьЗначение(КлючЗапроса, "42");
ИдЗапроса = ОтелКонтекст.Получить(КлючЗапроса); // "42"
Токен.Закрыть();

См. также

ОтелОбластьИнструментирования

Класс InstrumentationScope по спецификации OpenTelemetry.

Описание

Описывает библиотеку инструментации, создавшую телеметрию. Используется в трассировщике, логгере и метре для группировки данных при экспорте. Аналог Java SDK: io.opentelemetry.sdk.common.InstrumentationScopeInfo.

Конструктор

Параметр	Тип	По умолчанию	Описание
`Имя`	`Строка`	—	Имя инструментирующей библиотеки
`Версия`	`Строка`	`""`	Версия библиотеки
`Атрибуты`	`ОтелАтрибуты`	`Неопределено`	Атрибуты скоупа. Область хранит их копию: последующие изменения переданного объекта область не меняют
`АдресСхемы`	`Строка`	`""`	URL схемы телеметрии

Методы

Имя

Возвращает имя инструментирующей библиотеки.

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

Версия

Возвращает версию библиотеки.

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

Атрибуты

Возвращает копию атрибутов скоупа. Атрибуты входят в идентичность области, поэтому изменение возвращенного объекта область не меняет.

Возвращает: ОтелАтрибуты, Неопределено

АдресСхемы

Возвращает URL схемы телеметрии.

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

Ключ

Возвращает ключ идентичности области для кэширования трассировщиков, метров и логгеров и для группировки при экспорте. Ключи совпадают, только если совпадают все параметры: имя, версия, адрес схемы и атрибуты (порядок атрибутов не важен). Безопасен к Неопределено.

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

БиблиотекаИнструментирования

Возвращает ЭтотОбъект как InstrumentationLibrary (deprecated). Сохранен для обратной совместимости — InstrumentationLibrary содержит те же Имя и Версия, что и InstrumentationScope.

Возвращает: ОтелОбластьИнструментирования

См. также

ОтелПостроительBaggage

Построитель Baggage (BaggageBuilder) по спецификации OpenTelemetry.

Описание

Fluent API для создания иммутабельного ОтелBaggage. Аналог Java SDK: Baggage.builder().

Конструктор

Параметр	Тип	По умолчанию	Описание
`НачальныеЗначения`	`Соответствие`	`Неопределено`	Начальные значения (для `toBuilder`)
`НачальныеМетаданные`	`Соответствие`	`Неопределено`	Начальные метаданные (для `toBuilder`)

Методы

Установить

Устанавливает пару ключ-значение с опциональными метаданными.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ элемента
`Значение`	`Строка`	—	Значение элемента
`НовыеМетаданные`	`Строка`	`""`	Метаданные элемента

Возвращает: ОтелПостроительBaggage — ЭтотОбъект для fluent API

Удалить

Удаляет ключ.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Ключ элемента для удаления

Возвращает: ОтелПостроительBaggage — ЭтотОбъект для fluent API

Построить

Создает иммутабельный экземпляр Baggage.

Возвращает: ОтелBaggage — созданный Baggage

Пример

bsl

Baggage = Новый ОтелПостроительBaggage()
    .Установить("userId", "12345")
    .Установить("tenantId", "abc", "metadata-value")
    .Построить();

См. также

ОтелBaggage

ОтелПостроительSdk

Построитель OpenTelemetry SDK (OpenTelemetrySdkBuilder).

Описание

Предоставляет fluent API для сборки ОтелSdk из отдельных провайдеров. Аналог Java SDK: OpenTelemetrySdk.builder().

Методы

УстановитьПровайдерТрассировки

Устанавливает провайдер трассировки.

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

Возвращает: ОтелПостроительSdk — ЭтотОбъект для fluent API

УстановитьПровайдерЛогирования

Устанавливает провайдер логирования.

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

Возвращает: ОтелПостроительSdk — ЭтотОбъект для fluent API

УстановитьПровайдерМетрик

Устанавливает провайдер метрик.

Параметр	Тип	По умолчанию	Описание
`Провайдер`	`ОтелПровайдерМетрик`	—	Провайдер метрик

Возвращает: ОтелПостроительSdk — ЭтотОбъект для fluent API

УстановитьПропагаторы

Устанавливает пропагаторы контекста.

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелКомпозитныйПропагатор`	—	Пропагатор контекста, модуль или массив пропагаторов

Возвращает: ОтелПостроительSdk — ЭтотОбъект для fluent API

УстановитьТаймаутЗакрытия

Устанавливает таймаут, с которым SDK закрывается, если Закрыть вызван без таймаута. Сам SDK переменные окружения не читает: OTEL_SDK_SHUTDOWN_TIMEOUT применяет автоконфигурация.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	—	Таймаут в миллисекундах, `0` — без ограничения (по умолчанию у SDK `30000`)

Возвращает: ОтелПостроительSdk — ЭтотОбъект для fluent API

Построить

Создает экземпляр OpenTelemetry SDK.

Возвращает: ОтелSdk — настроенный экземпляр SDK

ПостроитьИЗарегистрироватьГлобально

Создает экземпляр SDK и регистрирует его глобально. Аналог Java SDK: OpenTelemetrySdk.builder().buildAndRegisterGlobal().

Возвращает: ОтелSdk — настроенный и глобально зарегистрированный экземпляр SDK

Пример

bsl

Сдк = Новый ОтелПостроительSdk()
    .УстановитьПровайдерТрассировки(ПровайдерТрассировки)
    .УстановитьПровайдерЛогирования(ПровайдерЛогирования)
    .УстановитьПровайдерМетрик(ПровайдерМетрик)
    .УстановитьПропагаторы(Пропагатор)
    .ПостроитьИЗарегистрироватьГлобально();

См. также

ОтелПостроительРесурса

Построитель ресурса — расширение SDK: в спецификации OpenTelemetry построителя ресурса нет.

Описание

Fluent API для создания ОтелРесурс с произвольными атрибутами. Аналог Java SDK: io.opentelemetry.sdk.resources.ResourceBuilder.

Новый построитель пуст, как Resource.builder(): ресурс получает только установленные атрибуты. Построитель с атрибутами существующего ресурса возвращает ОтелРесурс.ВПостроитель(), например ОтелРесурсы.ПоУмолчанию().ВПостроитель().

Методы

Установить

Устанавливает атрибут ресурса.

Параметр	Тип	По умолчанию	Описание
`Ключ`	`Строка`	—	Имя атрибута
`Значение`	`Произвольный`	—	Значение атрибута

Возвращает: ОтелПостроительРесурса — ЭтотОбъект для fluent API

УстановитьВсе

Устанавливает несколько атрибутов из ОтелАтрибуты.

Параметр	Тип	По умолчанию	Описание
`Значение`	`ОтелАтрибуты`	—	Атрибуты для добавления

Возвращает: ОтелПостроительРесурса — ЭтотОбъект для fluent API

УстановитьАдресСхемы

Устанавливает URL схемы семантических атрибутов ресурса.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Строка`	—	URL схемы (например, `"https://opentelemetry.io/schemas/1.44.0"`)

Возвращает: ОтелПостроительРесурса — ЭтотОбъект для fluent API

Построить

Создает ресурс из установленных атрибутов и адреса схемы.

Возвращает: ОтелРесурс — созданный ресурс

Пример

bsl

Ресурс = ОтелРесурсы.ПоУмолчанию().ВПостроитель()
    .Установить("service.name", "мой-сервис")
    .Установить("service.version", "1.0.0")
    .Построить();

См. также

ОтелРезультатЗакрытия

Результат операции закрытия или принудительной выгрузки.

Описание

Аналог CompletableResultCode для операций Shutdown/ForceFlush по спецификации OpenTelemetry SDK. По умолчанию создаётся успешный результат.

Конструктор

Параметр	Тип	По умолчанию	Описание
`НовыйУспех`	`Булево`	`Истина`	Признак успешного завершения
`НовоеОписание`	`Строка`	`""`	Описание ошибки
`НовоеИстекло`	`Булево`	`Ложь`	Признак истечения таймаута

Методы

Успешно

Возвращает признак успешного завершения операции.

Возвращает: Булево

ИстекТаймаут

Возвращает признак истечения таймаута.

Возвращает: Булево

Описание

Возвращает описание ошибки.

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

См. также

ОтелРезультатЭкспорта

Результат асинхронной операции экспорта.

Описание

Аналог CompletableResultCode из Java SDK. Используется процессорами и экспортерами для возврата результата операций Export, ForceFlush. Может содержать обещание для ожидания завершения асинхронных операций.

Конструктор

Параметр	Тип	По умолчанию	Описание
`Статус`	`Число`	`-1`	Начальный статус: `0` = успех, `1` = ошибка, `-1` = в процессе
`Обещание`	`Произвольный`	`Неопределено`	Объект обещания для async-операций

Методы

Успешно

Возвращает признак успешности результата.

Возвращает: Булево — Истина, если операция завершилась успешно

ИстекТаймаут

Возвращает признак истечения таймаута.

Возвращает: Булево — Истина, если операция завершилась по таймауту

Статус

Возвращает числовой код статуса результата.

Возвращает: Число — 0 = успех, 1 = ошибка, 2 = таймаут, -1 = в процессе

Ожидать

Блокирующее ожидание завершения операции. Если результат содержит обещание, ожидает его завершения.

Параметр	Тип	По умолчанию	Описание
`ТаймаутМс`	`Число`	`0`	Таймаут ожидания в миллисекундах (0 = без ограничения)

Возвращает: ОтелРезультатЭкспорта — ссылка на себя для цепочки вызовов

См. также

ОтелРезультатыЗакрытия

Модуль-фабрика результатов закрытия и принудительной выгрузки — объектов ОтелРезультатЗакрытия.

Описание

ОтелРезультатЗакрытия возвращают Закрыть процессоров, экспортеров, читателей метрик, провайдеров и ОтелSdk. Свой процессор или экспортер возвращает из Закрыть результат функций Успех(), Ошибка(Описание) или Таймаут() этого модуля. Аналог Java SDK: CompletableResultCode.ofSuccess, ofFailure.

Провайдеры закрывают и сбрасывают процессоры (провайдер метрик — читатели) функциями этого модуля. Метод Закрыть или СброситьБуфер вызывается у каждого компонента, даже если предыдущий бросил исключение или общий срок истёк; компонент получает время, оставшееся до срока (после срока — 1 мс). Если метод компонента не принимает таймаут, он вызывается без параметра. Результаты сводятся в один:

ошибка — если хоть один компонент вернул неуспешный результат без признака таймаута, вернул Ложь или бросил исключение; описания ошибок соединяются через ; ;
иначе таймаут — если компонент вернул таймаут или общий срок истёк;
иначе успех. Результат Неопределено (например, у процедуры Закрыть) считается успехом.

Остальные экспортные функции модуля служебные (см. «Внутренние функции»).

Функции

Успех

Создаёт успешный результат: Успешно() = Истина, ИстекТаймаут() = Ложь, Описание() — пустая строка.

Возвращает: ОтелРезультатЗакрытия — успех

Ошибка

Создаёт результат с ошибкой: Успешно() = Ложь, ИстекТаймаут() = Ложь. Описание попадает в сведённый результат провайдера и в результат ОтелSdk.Закрыть().

Параметр	Тип	По умолчанию	Описание
`Описание`	`Строка`	—	Описание ошибки

Возвращает: ОтелРезультатЗакрытия — ошибка

Таймаут

Создаёт результат истечения таймаута: Успешно() = Ложь, ИстекТаймаут() = Истина, Описание() — "Таймаут операции закрытия".

Возвращает: ОтелРезультатЗакрытия — таймаут

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

ЗакрытьВсе — закрывает компоненты (процессоры, читатели) в пределах общего срока и сводит результаты;
ВызватьУВсех — вызывает метод (Закрыть, СброситьБуфер) у каждого компонента в пределах общего срока и сводит результаты;
СброситьИЗакрыть — сбрасывает буфер компонента и закрывает его в пределах общего срока;
ЗакрытьЭкспортерПослеЭкспорта — Shutdown экспортера простого процессора: дожидается текущего экспорта, сбрасывает буфер экспортера и закрывает его;
ВызватьМетод — вызывает метод компонента, передавая столько параметров, сколько он принимает;
ОставшеесяВремя — время до общего срока, не меньше 1 мс (0, если срок не ограничен);
СрокИстек — истёк ли общий срок операции;
ТаймаутДоСрока — таймаут вызова, ограниченный временем до срока;
МеньшийТаймаут — меньший из двух таймаутов (0 и Неопределено — без ограничения);
ВызватьВПределахСрока — вызывает метод компонента с оставшимся временем, исключение возвращает ошибкой;
Свести — сводит результаты нескольких операций в один по правилам из «Описания»;
ЗакрытьТранспортЭкспортера — закрывает транспорт экспортера, если транспорт создала библиотека (автоконфигурация, файл конфигурации).

Пример

bsl

// Фрагмент своего процессора спанов (Экспортер - экспортер, переданный в конструктор):
// закрытие выгружает буфер экспортера и закрывает его
Функция Закрыть(ТаймаутМс = 0) Экспорт
    Попытка
        РезультатСброса = Экспортер.СброситьБуфер(ТаймаутМс);
        Экспортер.Закрыть();
    Исключение
        Возврат ОтелРезультатыЗакрытия.Ошибка(ОписаниеОшибки());
    КонецПопытки;
    Если РезультатСброса.ИстекТаймаут() Тогда
        Возврат ОтелРезультатыЗакрытия.Таймаут();
    ИначеЕсли НЕ РезультатСброса.Успешно() Тогда
        Возврат ОтелРезультатыЗакрытия.Ошибка("Сбой выгрузки буфера экспортера");
    КонецЕсли;
    Возврат ОтелРезультатыЗакрытия.Успех();
КонецФункции

См. также

ОтелРезультатыЭкспорта

Модуль-фабрика результатов экспорта и принудительной выгрузки — объектов ОтелРезультатЭкспорта.

Описание

ОтелРезультатЭкспорта возвращают СброситьБуфер процессоров, экспортеров, провайдеров и ОтелSdk. Свой процессор или экспортер создаёт результат функциями Успех(), Ошибка() и Таймаут() этого модуля, а результаты нескольких операций сводит в один функцией ОжидатьВсе(). Аналог Java SDK: CompletableResultCode.ofSuccess, ofFailure, ofAll.

Результат СброситьБуфер процессоров провайдер сводит по правилам ОтелРезультатыЗакрытия: Таймаут() даёт таймаут, Ошибка() — ошибку, Неопределено считается успехом. Так же пакетный процессор читает результат СброситьБуфер экспортера.

Остальные экспортные функции модуля служебные (см. «Внутренние функции»).

Функции

Успех

Создаёт успешный результат: статус 0, Успешно() = Истина.

Возвращает: ОтелРезультатЭкспорта — успех

Ошибка

Создаёт результат с ошибкой: статус 1, Успешно() = Ложь, ИстекТаймаут() = Ложь. Описания ошибки у ОтелРезультатЭкспорта нет, в отличие от ОтелРезультатыЗакрытия.Ошибка(Описание).

Возвращает: ОтелРезультатЭкспорта — ошибка

Таймаут

Создаёт результат истечения таймаута: статус 2, Успешно() = Ложь, ИстекТаймаут() = Истина.

Возвращает: ОтелРезультатЭкспорта — таймаут

ОжидатьВсе

Ожидает завершения каждого результата (ОтелРезультатЭкспорта.Ожидать) и сводит результаты в один. Результаты проверяются по порядку, итог определяет первый неуспешный: таймаут, если у него истёк таймаут, иначе ошибка. Если все результаты успешны или массив пуст — успех. Элементы другого типа (например, Неопределено) пропускаются с предупреждением в логе. Так ОтелSdk.СброситьБуфер() сводит результаты провайдеров.

Параметр	Тип	По умолчанию	Описание
`МассивРезультатов`	`Массив` из `ОтелРезультатЭкспорта`	—	Результаты для сведения
`ТаймаутМс`	`Число`	`0`	Время ожидания каждого результата в миллисекундах (`0` — без ограничения); ждать нужно только результату с обещанием, результаты `Успех()`, `Ошибка()` и `Таймаут()` готовы сразу

Возвращает: ОтелРезультатЭкспорта — успех, ошибка или таймаут

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

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

РезультатСбора — результат сбора метрик по списку сбоев: ошибка, таймаут (если все сбои — таймауты) или успех;
ИзРезультатаЗакрытия — переводит ОтелРезультатЗакрытия (сведённый результат ForceFlush) в ОтелРезультатЭкспорта;
СброситьБуферПослеЭкспорта — ForceFlush экспортера простого процессора: дожидается экспорта, начатого в другом потоке, и сбрасывает буфер экспортера;
СОбещанием — результат «в процессе» (статус -1) с обещанием библиотеки async; модули SDK её сейчас не вызывают. Статус такого результата не меняется и после выполнения обещания, поэтому SDK считает его неуспешным.

Пример

bsl

// Фрагмент своего процессора спанов, который отдаёт спаны нескольким экспортерам
// (Экспортеры - массив экспортеров, переменная объекта)
Функция СброситьБуфер(ТаймаутМс = 0) Экспорт
    НачалоМс = ТекущаяУниверсальнаяДатаВМиллисекундах();
    Результаты = Новый Массив;
    Для Каждого Экспортер Из Экспортеры Цикл
        ПрошлоМс = ТекущаяУниверсальнаяДатаВМиллисекундах() - НачалоМс;
        Если ТаймаутМс > 0 И ПрошлоМс >= ТаймаутМс Тогда
            Результаты.Добавить(ОтелРезультатыЭкспорта.Таймаут());
            Прервать;
        КонецЕсли;
        ОстатокМс = ?(ТаймаутМс > 0, ТаймаутМс - ПрошлоМс, 0);
        Попытка
            Результаты.Добавить(Экспортер.СброситьБуфер(ОстатокМс));
        Исключение
            Результаты.Добавить(ОтелРезультатыЭкспорта.Ошибка());
        КонецПопытки;
    КонецЦикла;
    // Успех, если все экспортеры сбросили буфер; иначе ошибка или таймаут
    Возврат ОтелРезультатыЭкспорта.ОжидатьВсе(Результаты);
КонецФункции

См. также

ОтелРесурс

Класс описания ресурса (Resource) по спецификации OpenTelemetry.

Описание

Ресурс описывает сущность, производящую телеметрию: сервис, хост, процесс и т.д. Аналог Java SDK: io.opentelemetry.sdk.resources.Resource.

Конструктор создаёт ресурс ровно из переданных атрибутов и ничего не добавляет сам. Готовые ресурсы возвращает модуль ОтелРесурсы:

ОтелРесурсы.ПоУмолчанию() — обязательные атрибуты SDK (service.name, telemetry.sdk.*); его получают провайдеры, которым ресурс не передан;
ОтелРесурсы.ИзДетекторов() — атрибуты детекторов ресурса;
ОтелРесурсы.ИзОкружения() — атрибуты из OTEL_RESOURCE_ATTRIBUTES и OTEL_SERVICE_NAME.

Автоконфигурация и файловая конфигурация собирают ресурс SDK из этих частей сами. Ресурс с дополнительными атрибутами собирается через ОтелПостроительРесурса или Слить.

Конструктор

Параметр	Тип	По умолчанию	Описание
`НачальныеАтрибуты`	`ОтелАтрибуты`, `Соответствие`	`Неопределено`	Атрибуты ресурса. Копируются: изменение переданной коллекции ресурс не меняет. Без атрибутов ресурс пустой
`НачальныйАдресСхемы`	`Строка`	`""`	URL схемы ресурса

Методы

Атрибуты

Возвращает атрибуты ресурса.

Возвращает: ОтелАтрибуты — атрибуты ресурса

АдресСхемы

Возвращает URL схемы ресурса. OTLP-экспортёры передают непустой URL в поле schemaUrl группы ресурса; ресурсы с одинаковыми атрибутами и разными схемами экспортируются отдельными группами.

Возвращает: Строка — URL схемы или пустая строка

Слить

Создает новый ресурс как результат слияния текущего с другим. Атрибуты другого ресурса имеют приоритет. Если адрес схемы задан только у одного ресурса, он переходит в результат; если адреса разные, у результата адрес пустой, а в лог пишется ошибка.

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

Возвращает: ОтелРесурс — новый ресурс со слитыми атрибутами

ВПостроитель

Возвращает построитель с атрибутами и адресом схемы этого ресурса. Аналог Java SDK: Resource.toBuilder().

Возвращает: ОтелПостроительРесурса — построитель с копией ресурса

ВСоответствиеOtlp

Преобразует ресурс в соответствие формата OTLP JSON.

Возвращает: Соответствие — {"attributes": [...]}

Пример

bsl

// Ресурс по умолчанию с атрибутами приложения
Ресурс = ОтелРесурсы.ПоУмолчанию().ВПостроитель()
    .Установить("service.name", "мой-сервис")
    .Установить("service.version", "1.0.0")
    .Построить();

// Вместе с детекторами и переменными окружения
Ресурс = ОтелРесурсы.ПоУмолчанию()
    .Слить(ОтелРесурсы.ИзДетекторов())
    .Слить(ОтелРесурсы.ИзОкружения());

// Ресурс ровно из своих атрибутов
Атрибуты = Новый Соответствие();
Атрибуты.Вставить("service.name", "мой-сервис");
Ресурс = Новый ОтелРесурс(Атрибуты, "https://opentelemetry.io/schemas/1.44.0");

См. также

ОтелРесурсы

Модуль-фабрика ресурсов ОтелРесурс.

Описание

Аналог статических методов Java SDK Resource.empty() и Resource.getDefault(), а также ресурсов детекторов и окружения, которые в Java собирает autoconfigure. Каждая функция возвращает новый ресурс: изменение одного не затрагивает другие.

Автоконфигурация (ОтелАвтоконфигурация) собирает ресурс SDK как ПоУмолчанию(), поверх — ИзДетекторов() с детекторами по умолчанию и переданными в Инициализировать детекторами, затем ИзОкружения(), поверх — атрибуты из менеджера параметров. Файловая конфигурация берёт ПоУмолчанию() и ИзДетекторов(), а переменные окружения, кроме подставленных в файл, не читает.

Функции

Пустой

Возвращает пустой ресурс. Аналог Resource.empty().

Возвращает: ОтелРесурс — ресурс без атрибутов и адреса схемы

ПоУмолчанию

Возвращает ресурс с атрибутами, которые SDK обязан заполнять сам (спецификация Resource SDK, SDK-provided resource attributes). Аналог Resource.getDefault(). Детекторов и переменных окружения в нём нет. Этот ресурс получают провайдеры трассировки, логирования и метрик и читатели метрик, которым ресурс не передан явно.

Атрибут	Значение
`service.name`	`unknown_service:oscript`
`telemetry.sdk.name`	`oscript-opentelemetry`
`telemetry.sdk.language`	`oscript`
`telemetry.sdk.version`	версия пакета

Возвращает: ОтелРесурс — ресурс по умолчанию без адреса схемы

ДетекторыПоУмолчанию

Возвращает новый массив детекторов по умолчанию, в таком порядке:

Массив можно изменить и передать в ИзДетекторов: убрать детектор, добавить свой. Каждый вызов возвращает новый массив и новые детекторы.

Возвращает: Массив из ИнтерфейсДетекторРесурса

ИзДетекторов

Возвращает слияние ресурсов переданных детекторов в порядке коллекции: атрибут детектора, идущего позже, важнее. Без параметра — слияние детекторов ДетекторыПоУмолчанию().

Переданные детекторы заменяют детекторы по умолчанию, а не дополняют их. Каждый детектор должен объявлять &Реализует("ИнтерфейсДетекторРесурса") и реализовывать ИнтерфейсДетекторРесурса, иначе выбрасывается исключение: это ошибка настройки, и SDK по принципам обработки ошибок спецификации может завершиться с ошибкой при инициализации. Исключение в Обнаружить() или результат не ОтелРесурс не прерывают сбор: ошибка пишется в лог oscript.lib.opentelemetry.resource, детектор пропускается.

Параметр	Тип	Описание
`Детекторы`	`Массив`, `ФиксированныйМассив` из `ИнтерфейсДетекторРесурса`	Детекторы ресурса. Необязательный, по умолчанию — детекторы по умолчанию

Возвращает: ОтелРесурс — атрибуты детекторов; у детекторов по умолчанию адрес схемы https://opentelemetry.io/schemas/1.44.0

ИзОкружения

Возвращает ресурс из переменных окружения: атрибуты OTEL_RESOURCE_ATTRIBUTES в формате ключ=значение через запятую, с percent-декодированием, и имя сервиса OTEL_SERVICE_NAME. Имя из OTEL_SERVICE_NAME важнее service.name из OTEL_RESOURCE_ATTRIBUTES.

Если в OTEL_RESOURCE_ATTRIBUTES есть ошибка — элемент не в формате ключ=значение, пустой ключ или некорректный percent-encoding, — значение отбрасывается целиком, а ошибка пишется в лог oscript.lib.opentelemetry.resource. Пустые элементы (лишние запятые) пропускаются.

Возвращает: ОтелРесурс — атрибуты окружения без адреса схемы; без переменных — пустой ресурс

Пример

bsl

// Ресурс для провайдеров, собранных вручную: как у автоконфигурации
Ресурс = ОтелРесурсы.ПоУмолчанию()
    .Слить(ОтелРесурсы.ИзДетекторов())
    .Слить(ОтелРесурсы.ИзОкружения());

Провайдер = Новый ОтелПровайдерТрассировки(Ресурс);

bsl

// Детекторы по умолчанию без детектора хоста: host.name и os.type не попадут в ресурс
Детекторы = ОтелРесурсы.ДетекторыПоУмолчанию();
Детекторы.Удалить(0);
Ресурс = ОтелРесурсы.ПоУмолчанию()
    .Слить(ОтелРесурсы.ИзДетекторов(Детекторы))
    .Слить(ОтелРесурсы.ИзОкружения());

Свой детектор — в примере ИнтерфейсДетекторРесурса.

См. также

ОтелСемантическиеСоглашения

Модуль — константы семантических соглашений (Semantic Conventions) OpenTelemetry.

Описание

Аналог пакета io.opentelemetry.semconv в Java. Возвращает имена атрибутов и метрик, которыми инструментирования описывают обращения к базам данных, серверам, ошибки и код, а также рекомендованные границы бакетов гистограмм. Инструментирование, использующее эти функции вместо строковых литералов, не расходится с соглашениями и с другими инструментированиями в одном трейсе.

Значения соответствуют стабильной части semantic-conventions 1.30+ (db.*, server.*, error.type, code.*).

Атрибуты баз данных

Функция	Значение
`СистемаБД()`	`db.system.name`
`ПространствоИменБД()`	`db.namespace`
`ИмяКоллекцииБД()`	`db.collection.name`
`ИмяОперацииБД()`	`db.operation.name`
`ТекстЗапросаБД()`	`db.query.text`
`ВозвращенныеСтрокиБД()`	`db.response.returned_rows`
`ИмяПулаСоединенийБД()`	`db.client.connection.pool.name`
`СостояниеСоединенияБД()`	`db.client.connection.state`
`СостояниеСоединенияИспользуется()`	`used` — значение состояния соединения
`СостояниеСоединенияСвободно()`	`idle` — значение состояния соединения

Атрибуты сервера, ошибок и кода

Функция	Значение
`АдресСервера()`	`server.address`
`ПортСервера()`	`server.port`
`ТипОшибки()`	`error.type`
`ТипОшибкиДругой()`	`_OTHER` — значение типа ошибки, когда инструментирование не определило свой тип (см. ОтелУтилиты.ТипОшибки)
`ПространствоИменКода()`	`code.namespace`
`ИмяФункцииКода()`	`code.function.name`

Метрики клиента баз данных

Функция	Значение
`МетрикаДлительностиОперацииБД()`	`db.client.operation.duration`
`МетрикаКоличестваСоединенийБД()`	`db.client.connection.count`
`МетрикаПределаСоединенийБД()`	`db.client.connection.max`
`МетрикаОжидающихЗапросовСоединенийБД()`	`db.client.connection.pending_requests`
`МетрикаВремениОжиданияСоединенияБД()`	`db.client.connection.wait_time`
`МетрикаВремениСозданияСоединенияБД()`	`db.client.connection.create_time`
`МетрикаТаймаутовСоединенийБД()`	`db.client.connection.timeouts`

ГраницыДлительностиОперацииБД

Рекомендованные границы бакетов гистограммы db.client.operation.duration в секундах: 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10. Каждый вызов возвращает новый массив, поэтому вызывающий может его менять.

Возвращает: Массив из Число

Пример

bsl

Атрибуты = Новый Соответствие;
Атрибуты.Вставить(ОтелСемантическиеСоглашения.СистемаБД(), "postgresql");
Атрибуты.Вставить(ОтелСемантическиеСоглашения.ИмяОперацииБД(), "SELECT");
Атрибуты.Вставить(ОтелСемантическиеСоглашения.ИмяКоллекцииБД(), "users");

Спан = Трассировщик.НачатьСпан("SELECT users", ОтелВидСпана.Клиент(), Атрибуты);

Совет = Новый Структура("ГраницыГистограммы", ОтелСемантическиеСоглашения.ГраницыДлительностиОперацииБД());
Гистограмма = Метр.СоздатьГистограмму(
    ОтелСемантическиеСоглашения.МетрикаДлительностиОперацииБД(),
    "Длительность запросов к СУБД", "s", Совет);

ОтелТокенКонтекста

Токен (Token) контекста по спецификации OpenTelemetry Context API.

Описание

Возвращается из ОтелКонтекст.ПрисоединитьКонтекст() и должен быть передан в ОтелКонтекст.ОтсоединитьКонтекст() для восстановления предыдущего контекста. Поддерживает RAII-паттерн через метод Закрыть().

Аналоги: Java Scope, Python opentelemetry.context.Token, Go detach token.

Конструктор

Параметр	Тип	По умолчанию	Описание
`ПараметрГлубина`	`Число`	`0`	Глубина стека контекстов на момент присоединения
`ПараметрПоток`	`ПотокИсполнения`	`Неопределено`	Поток, в котором был выдан токен

Методы

Отсоединен

Возвращает признак того, что токен уже отсоединён (Detach был вызван).

Возвращает: Булево — Истина, если токен отсоединён

ПометитьОтсоединенным

Помечает токен как отсоединённый. Внутренний метод, вызывается из ОтелКонтекст.ОтсоединитьКонтекст().

Закрыть

Отсоединяет контекст, восстанавливая предыдущий (сахар над ОтелКонтекст.ОтсоединитьКонтекст). Повторный вызов идемпотентен.

Пример

bsl

// RAII-паттерн
Токен = Спан.СделатьТекущим();
Попытка
    // ... работа в контексте спана ...
Исключение
    Спан.ЗаписатьИсключение(ИнформацияОбОшибке());
КонецПопытки;
Токен.Закрыть(); // обязательно вызвать перед Завершить()
Спан.Завершить();

// Явный Detach
Токен = ОтелКонтекст.ПрисоединитьКонтекст(Контекст);
// ... работа ...
ОтелКонтекст.ОтсоединитьКонтекст(Токен);

См. также

ОтелУтилиты

Модуль вспомогательных функций SDK: время в формате OpenTelemetry, часы, генератор идентификаторов и тип ошибки для exception.type и error.type, общий для SDK и библиотек инструментирования.

Описание

Время в API библиотеки — строка с числом наносекунд от начала эпохи Unix (1970-01-01 00:00:00 UTC), например "1700000000500000000". В этих единицах метки времени передаёт OTLP. Спецификация допускает точность от миллисекунд до наносекунд: время, которое SDK ставит само, имеет точность до миллисекунд (последние шесть цифр — нули), а время из внешнего источника с большей точностью передаётся без потерь.

Своё время задают, когда событие уже произошло: время начала спана, если момент создания спана прошёл, время окончания спана, время события спана, время записи лога. Строку для такого времени дают функции модуля:

текущее время — ТекущееВремяВНаносекундах();
время, засечённое через ТекущаяУниверсальнаяДатаВМиллисекундах(), — МиллисекундыВНаносекунды().

Часы и генератор идентификаторов модуля общие для всего SDK в процессе. Генератор у конкретного провайдера трассировки задаёт ОтелПостроительПровайдераТрассировки.УстановитьГенераторИд.

Функции

ТекущееВремяВНаносекундах

Возвращает текущее время. Если установлены свои часы (см. УстановитьЧасы), время берётся из них.

Возвращает: Строка — наносекунды от начала эпохи Unix

МиллисекундыВНаносекунды

Переводит время из миллисекунд от 0001-01-01 UTC — формата ТекущаяУниверсальнаяДатаВМиллисекундах() и библиотеки logos — в наносекунды от начала эпохи Unix.

Параметр	Тип	По умолчанию	Описание
`МиллисекундыОт0001`	`Число`	—	Целое число миллисекунд от 0001-01-01 UTC

Возвращает: Строка — наносекунды от начала эпохи Unix

УстановитьЧасы

Устанавливает свои часы (аналог Java SDK: SdkTracerProviderBuilder.setClock). Часы — объект с функцией ТекущееВремяВНаносекундах(), которая возвращает строку наносекунд от начала эпохи Unix. Часы общие для всего SDK: из них берётся всё время, которое SDK ставит само, — начало и окончание спанов, время событий, записей логов, точек метрик и exemplars.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Произвольный`	—	Объект с функцией `ТекущееВремяВНаносекундах()`

СброситьЧасы

Возвращает системные часы.

УстановитьГенераторИд

Устанавливает генератор идентификаторов для провайдеров трассировки, у которых свой генератор не задан. Генератор — объект с функциями СгенерироватьИдТрассировки() (32 hex-символа) и СгенерироватьИдСпана() (16 hex-символов). Идентификатор должен быть строчной hex-строкой нужной длины не из одних нулей; некорректный идентификатор пишется в лог как ошибка и заменяется идентификатором генератора по умолчанию (на основе УникальныйИдентификатор).

Параметр	Тип	По умолчанию	Описание
`Генератор`	`Произвольный`	—	Объект с функциями `СгенерироватьИдТрассировки()` и `СгенерироватьИдСпана()`

СброситьГенераторИд

Возвращает генератор идентификаторов по умолчанию.

УстановитьКлассификаторНативныхОшибок

Устанавливает свой классификатор ошибок без кода библиотеки errors, по которому ЗаписатьИсключение спана и запись лога заполняют exception.type. Классификатор — объект с функцией Классифицировать(ИнформацияОбОшибке), которая, как КлассификаторОшибок библиотеки errors, возвращает ошибку с кодом или Неопределено. Классификатор общий для всего SDK; по умолчанию — классификатор с правилами native-errors, созданный при загрузке модуля. Исключение классификатора SDK не пробрасывает: тип остаётся незаполненным.

Параметр	Тип	По умолчанию	Описание
`Значение`	`Произвольный`	—	Объект с функцией `Классифицировать(ИнформацияОбОшибке)`

СброситьКлассификаторНативныхОшибок

Возвращает классификатор нативных ошибок OneScript по умолчанию.

ТипИсключения

Возвращает значение exception.type — тот же тип, что ставят ЗаписатьИсключение спана и запись лога: код ошибки библиотеки errors, а у ошибки без кода — код классификатора нативных ошибок (numeric.division_by_zero, network.connection.refused и т.п.). Нужен библиотекам инструментирования, которые получают тип один раз и передают его явно: exception.type в ДополнительныеАтрибуты спана не запускает повторную классификацию.

Параметр	Тип	По умолчанию	Описание
`ИнформацияОбИсключении`	`ИнформацияОбОшибке`	—	Информация об исключении

Возвращает: Строка, Неопределено — код ошибки; Неопределено, если ошибка не распознана или передана не ИнформацияОбОшибке

ТипОшибки

Возвращает значение error.type для операции, завершившейся исключением: тип исключения (см. ТипИсключения), а если он не определён — _OTHER (ОтелСемантическиеСоглашения.ТипОшибкиДругой()), запасное значение семантических соглашений. Библиотеки инструментирования берут тип отсюда, чтобы error.type в спанах и метриках был одинаков.

Параметр	Тип	По умолчанию	Описание
`ИнформацияОбИсключении`	`ИнформацияОбОшибке`	—	Информация об исключении

Возвращает: Строка — тип ошибки

bsl

Исключение
    Ошибка = ИнформацияОбОшибке();
    Тип = ОтелУтилиты.ТипИсключения(Ошибка);
    Доп = Новый ОтелАтрибуты();
    Если Тип <> Неопределено Тогда
        Доп.Установить("exception.type", Тип);
    КонецЕсли;
    Спан.ЗаписатьИсключение(Ошибка, Доп);
    // Тот же тип без повторной классификации
    Спан.УстановитьАтрибут(ОтелСемантическиеСоглашения.ТипОшибки(),
        ?(Тип = Неопределено, ОтелСемантическиеСоглашения.ТипОшибкиДругой(), Тип));
КонецПопытки;

СтекВызововИсключения

Возвращает значение exception.stacktrace: описание ошибки и кадры стека OneScript, затем цепочку причин — описание каждой причины после Caused by: и её кадры. Этот формат пишут событие исключения спана (ОтелСпан.ЗаписатьИсключение) и запись лога (ОтелЗаписьЛога.УстановитьИсключение), так что стек одной ошибки в трассах и логах одинаков. Кадров движка .NET из ПодробноеОписаниеОшибки() в нём нет. У объекта без стека вызовов и причин — только описание.

Параметр	Тип	По умолчанию	Описание
`ИнформацияОбИсключении`	`ИнформацияОбОшибке`	—	Информация об исключении

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

text

app.calc.failed: Расчет не удался
  /app/Расчет.os / Метод Рассчитать / Строка 12
Caused by: Деление на ноль
  /app/Расчет.os / Метод Разделить / Строка 3
  /app/Расчет.os / Метод Рассчитать / Строка 10

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

СгенерироватьИдТрассировки, СгенерироватьИдСпана — идентификаторы для провайдера трассировки;
ВШестнадцатеричнуюСтроку, ИзШестнадцатеричнойСтроки, ЯвляетсяШестнадцатеричнойСтрокой, ЯвляетсяШестнадцатеричнойСтрокойВНижнемРегистре, ЯвляетсяВалиднымИдентификатором — разбор и проверка hex-значений для пропагаторов и сэмплера;
РаскодироватьURLСтрого — разбор percent-encoding в атрибутах ресурса из окружения;
ЗначениеАтрибутаВФорматОтел, ОграничитьЗначениеАтрибута — перевод значения атрибута в OTLP и лимиты длины и глубины;
ВерсияSDK, ВерсияПакета, UserAgentЭкспортераOtlp — версия SDK для ресурса и User-Agent экспортера;
РесурсДетектора — ресурс детекторов хоста, процесса и процессора;
ИдЭкземпляраСервиса — service.instance.id процесса для детектора экземпляра сервиса.

Функции Транслитерировать (кириллица в латиницу в нижнем регистре) и ПроверитьИмяМетрики (исключение, если имя не из символов a-z, A-Z, 0-9, _, ., - или начинается не с буквы) SDK не вызывает: имя инструмента проверяет метр по правилам спецификации.

Пример

bsl

// Операция уже прошла: время начала и окончания засечены заранее
Начало = ТекущаяУниверсальнаяДатаВМиллисекундах();
// ... операция ...
Окончание = ТекущаяУниверсальнаяДатаВМиллисекундах();

Спан = Трассировщик.НачатьСпан("Загрузка", , , , ОтелУтилиты.МиллисекундыВНаносекунды(Начало));
Спан.Завершить(ОтелУтилиты.МиллисекундыВНаносекунды(Окончание));

Публичный интерфейс библиотеки opentelemetry ​

Ядро ​

Трассировка ​

Логирование ​

Метрики ​

Экспорт ​

Пропагация ​

Конфигурация ​

Интеграции ​

ОтелАппендерLogos ​

Описание ​

Конструктор ​

Методы ​

ВывестиСобытие ​

Закрыть ​

УстановитьСвойство ​

УстановитьЛоггер ​

Логгер ​

Пример ​

ОтелАвтоконфигурация ​

Описание ​

Поддерживаемые переменные окружения ​

Функции ​

Инициализировать ​

СоздатьМенеджерПараметровПоУмолчанию ​

СоздатьРесурс ​

СоздатьТранспорт ​

СоздатьТранспортДляСигнала ​

СоздатьПровайдерТрассировки ​

СоздатьПровайдерЛогирования ​

СоздатьПровайдерМетрик ​

СоздатьПропагаторы ​

СоздатьЛимитыСпана ​

СоздатьЛимитыЗаписейЛога ​

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

Пример ​

YAML-конфигурация ​

См. также ​

ОтелКонфигурационнаяФабрика ​

Описание ​

Функции ​

Создать ​

СоздатьРесурс ​

СоздатьПровайдерТрассировки ​

СоздатьПровайдерЛогирования ​

СоздатьПровайдерМетрик ​

СоздатьПропагаторы ​

Процедуры ​

ЗарегистрироватьПровайдерКомпонента ​

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

Пример ​

См. также ​

ОтелКонфигурация ​

Описание ​

Конструктор ​

Поля ​

ОтелКонфигурация ​

ОтелКонфигурацияРесурса ​

ОтелКонфигурацияЛимитовАтрибутов ​

ОтелКонфигурацияПропагатора ​

ОтелКонфигурацияПровайдераТрассировки ​

ОтелКонфигурацияЛимитовСпана ​

ОтелКонфигурацияСэмплера ​

ОтелКонфигурацияПровайдераМетрик ​

ОтелКонфигурацияПредставления ​

ОтелКонфигурацияСелектораИнструментов ​

ОтелКонфигурацияПотокаМетрики ​

ОтелКонфигурацияАгрегации ​

ОтелКонфигурацияКлючейАтрибутов ​

ОтелКонфигурацияПровайдераЛогирования ​

ОтелКонфигурацияПакетногоПроцессора ​

ОтелКонфигурацияПростогоПроцессора ​

ОтелКонфигурацияПериодическогоЧитателя ​

ОтелКонфигурацияPullЧитателя ​

ОтелКонфигурацияЛимитовМощности ​

ОтелКонфигурацияЭкспортераOtlpHttp ​

ОтелКонфигурацияЭкспортераOtlpGrpc ​

ОтелКонфигурацияКонсольногоЭкспортера ​

ОтелКонфигурацияКомпонента ​

Пример ​

Публичный интерфейс библиотеки `opentelemetry`

Ядро

Трассировка

Логирование

Метрики

Экспорт

Пропагация

Конфигурация

Интеграции

ОтелАппендерLogos

Описание

Конструктор

Методы

ВывестиСобытие

Закрыть

УстановитьСвойство

УстановитьЛоггер

Логгер

Пример

ОтелАвтоконфигурация

Описание

Поддерживаемые переменные окружения

Функции

Инициализировать

СоздатьМенеджерПараметровПоУмолчанию

СоздатьРесурс

СоздатьТранспорт

СоздатьТранспортДляСигнала

СоздатьПровайдерТрассировки

СоздатьПровайдерЛогирования

СоздатьПровайдерМетрик

СоздатьПропагаторы

СоздатьЛимитыСпана

СоздатьЛимитыЗаписейЛога

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

Пример

YAML-конфигурация

См. также

ОтелКонфигурационнаяФабрика

Описание

Функции

Создать

СоздатьРесурс

СоздатьПровайдерТрассировки

СоздатьПровайдерЛогирования

СоздатьПровайдерМетрик

СоздатьПропагаторы

Процедуры

ЗарегистрироватьПровайдерКомпонента

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

Пример

См. также

ОтелКонфигурация

Описание

Конструктор

Поля

ОтелКонфигурация

ОтелКонфигурацияРесурса

ОтелКонфигурацияЛимитовАтрибутов

ОтелКонфигурацияПропагатора

ОтелКонфигурацияПровайдераТрассировки

ОтелКонфигурацияЛимитовСпана

ОтелКонфигурацияСэмплера

ОтелКонфигурацияПровайдераМетрик

ОтелКонфигурацияПредставления

ОтелКонфигурацияСелектораИнструментов

ОтелКонфигурацияПотокаМетрики

ОтелКонфигурацияАгрегации

ОтелКонфигурацияКлючейАтрибутов

ОтелКонфигурацияПровайдераЛогирования

ОтелКонфигурацияПакетногоПроцессора

ОтелКонфигурацияПростогоПроцессора

ОтелКонфигурацияПериодическогоЧитателя

ОтелКонфигурацияPullЧитателя

ОтелКонфигурацияЛимитовМощности

ОтелКонфигурацияЭкспортераOtlpHttp

ОтелКонфигурацияЭкспортераOtlpGrpc

ОтелКонфигурацияКонсольногоЭкспортера

ОтелКонфигурацияКомпонента

Пример