Skip to content

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

Модель файла конфигурации: объекты с настройками 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_urlURL схемы ресурса; "" — не задан

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

Секции 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Максимальное количество атрибутов спана; Неопределено — не задано
МаксСобытийЧисло128event_count_limitМаксимальное количество событий спана
МаксЛинковЧисло128link_count_limitМаксимальное количество линков спана
МаксАтрибутовНаСобытиеЧисло128event_attribute_count_limitМаксимальное количество атрибутов события
МаксАтрибутовНаЛинкЧисло128link_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.0trace_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 гистограмм обоих типов
МаксШкалаЧисло20max_scaleМаксимальная шкала base2_exponential_bucket_histogram — целое от -10 до 20
МаксРазмерЧисло160max_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_providerschedule_delayИнтервал фонового экспорта, мс; Неопределено — 5000 у спанов, 1000 у записей лога
ТаймаутЭкспортаЧисло30000export_timeoutТаймаут экспорта, мс
МаксРазмерОчередиЧисло2048max_queue_sizeМаксимальный размер очереди
МаксРазмерПакетаЧисло512max_export_batch_sizeМаксимальный размер пакета экспорта
ЭкспортерОтелКонфигурацияЭкспортераOtlpHttp, ОтелКонфигурацияЭкспортераOtlpGrpc, ОтелКонфигурацияКонсольногоЭкспортера, ОтелКонфигурацияКомпонента, НеопределеноНеопределеноexporterОбязательный экспортер: процессор без экспортера фабрика не создаёт — выбрасывает исключение. Экспортер, которого нет в SDK, — ОтелКонфигурацияКомпонента

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

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

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

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

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

ПолеТипПо умолчаниюКлюч в файлеОписание
ИнтервалЧисло60000intervalИнтервал периодического экспорта, мс
ТаймаутЧисло30000timeoutТаймаут экспорта, мс
ЭкспортерОтелКонфигурацияЭкспортера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, важнее лимита читателя.

ПолеТипПо умолчаниюКлюч в файлеОписание
ПоУмолчаниюЧисло2000defaultЛимит для видов инструментов без своего лимита; Неопределено — 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/<сигнал>
СжатиеСтрока""compressiongzip — сжатие gzip; none и "" — без сжатия. Другое значение, в том числе в другом регистре, — исключение фабрики
ТаймаутЧисло10000timeoutСрок каждого экспорта вместе с повторами и таймаут HTTP-запроса, мс; 0 — без ограничения
ЗаголовкиМассив из Структурапустой массивheadersHTTP-заголовки — структуры с полями Имя (из 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. Другое значение не проходит проверку модели
МаксРазмерЗапросаЧисло67108864max_request_sizeНаибольший размер тела запроса до сжатия, байт: запрос больше лимита не отправляется, экспорт неуспешен; 0 — без ограничения
МаксРазмерОтветаЧисло4194304max_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 и "" — без сжатия, другое значение — исключение фабрики
ТаймаутЧисло10000timeoutСрок каждого экспорта вместе с повторами и таймаут вызова gRPC, мс; 0 — без ограничения
ЗаголовкиМассив из Структурапустой массивheadersМетаданные вызова gRPC — структуры с полями Имя и Значение, как у otlp_http
СписокЗаголовковСтрока""headers_listМетаданные строкой в формате OTEL_EXPORTER_OTLP_HEADERS. При совпадении имён действует значение из Заголовки
ПредпочтениеВременнойАгрегацииСтрока""temporality_preferenceВременная агрегация метрик, как у otlp_http
АгрегацияГистограммПоУмолчаниюСтрока""default_histogram_aggregationАгрегация гистограмм по умолчанию, как у otlp_http
МаксРазмерЗапросаЧисло67108864max_request_sizeНаибольший размер сообщения запроса до сжатия, байт, как у otlp_http; 0 — без ограничения
МаксРазмерОтветаЧисло4194304max_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 только провайдер трассировки
Сдк = ОтелКонфигурационнаяФабрика.Создать(Модель);

См. также ​