ОтелКонфигурация
Модель файла конфигурации: объекты с настройками 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 мс. Фабрика работает с копией модели и саму модель не меняет. Поле, у которого значения по умолчанию нет (в колонке Неопределено), остаётся не заданным.
Ключи файла и поля модели:
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Конструктор
Новый ОтелКонфигурация()
Новый ОтелКонфигурацияРесурса()
Новый ОтелКонфигурацияЛимитовАтрибутов()
Новый ОтелКонфигурацияПропагатора()
Новый ОтелКонфигурацияПровайдераТрассировки()
Новый ОтелКонфигурацияЛимитовСпана()
Новый ОтелКонфигурацияСэмплера()
Новый ОтелКонфигурацияПровайдераМетрик()
Новый ОтелКонфигурацияПровайдераЛогирования()
Новый ОтелКонфигурацияПакетногоПроцессора()
Новый ОтелКонфигурацияПростогоПроцессора()
Новый ОтелКонфигурацияПериодическогоЧитателя()
Новый ОтелКонфигурация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. В секции сэмплера один ключ — тип сэмплера, под ключом — его параметры:
sampler:
parent_based:
root:
trace_id_ratio_based:
ratio: 0.1
remote_parent_not_sampled:
always_off:# процессоры получают все спаны, экспортер - 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»). Без провайдера фабрика выбрасывает исключение.
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, например экспортер пользователя:
exporter:
my_exporter: # Имя
url: http://example # СвойстваСпецификация Configuration SDK (Parse) требует сохранять конфигурацию компонента, которого нет в SDK, в общем виде. Фабрика создаёт такой компонент провайдером компонента, который получает Свойства как ОтелСвойстваКонфигурации; без провайдера — исключение (см. ОтелКонфигурационнаяФабрика, «Компоненты, которых нет в SDK»).
| Поле | Тип | По умолчанию | Ключ в файле | Описание |
|---|---|---|---|---|
Имя | Строка | "" | ключ компонента | Имя компонента, например tracecontext, random, my_exporter |
Свойства | Соответствие, Неопределено | Неопределено | значение под ключом | Свойства компонента как в файле — Соответствие, значения которого прочитаны из YAML без преобразования; Неопределено — ключ без значения (my_exporter:) |
Пример
#Использовать 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";
Сэмплер.Корневой = Корневой;
Провайдер.Сэмплер = Сэмплер;
КонецЕсли;
// Фабрика читает поля модели в момент вызова и проверяет измененную модель по схеме
Сдк = ОтелКонфигурационнаяФабрика.Создать(Модель);
ОтелГлобальный.Установить(Сдк);
// ...
Сдк.Закрыть();// Модель без файла: спаны отправляются по OTLP/HTTP, пропагаторы W3C
Экспортер = Новый ОтелКонфигурацияЭкспортераOtlpHttp();
Экспортер.Адрес = "http://collector:4318/v1/traces";
Процессор = Новый ОтелКонфигурацияПакетногоПроцессора();
Процессор.Экспортер = Экспортер;
Модель = Новый ОтелКонфигурация();
Модель.ФорматФайла = "1.0";
Модель.Ресурс = Новый ОтелКонфигурацияРесурса();
Модель.Ресурс.Атрибуты.Добавить(Новый Структура("Имя, Значение", "service.name", "мой-сервис"));
Модель.ПровайдерТрассировки = Новый ОтелКонфигурацияПровайдераТрассировки();
Модель.ПровайдерТрассировки.Процессоры.Добавить(Процессор);
Модель.Пропагатор = Новый ОтелКонфигурацияПропагатора();
Модель.Пропагатор.СписокСоставного = "tracecontext,baggage";
// Секций meter_provider и logger_provider нет: у SDK только провайдер трассировки
Сдк = ОтелКонфигурационнаяФабрика.Создать(Модель);