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

Модуль автоматической конфигурации 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

Интеграции

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

Логирование

Метрики

Пропагация

Трассировка

Экспорт

Ядро

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

Описание

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

Функции

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

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

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

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

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

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

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

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

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

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

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

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

Пример

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

См. также

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

Описание ​

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

Функции ​

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

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

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

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

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

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

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

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

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

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

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

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

Пример ​

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

См. также ​

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

Описание

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

Функции

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

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

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

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

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

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

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

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

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

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

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

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

Пример

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

См. также