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

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

Описание

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

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

• OTel File Configuration
• OTel Configuration Data Model

Формат файла: 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

Пример

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

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

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

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

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

Пример 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Читателя.

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