# Довідка по OBI Config v2 > Дізнайтеся, як налаштувати автономний OBI або приймач OBI Колектора за використовуючи Config v2. --- LLMS index: [llms.txt](/llms.txt) --- Config v2 доступний у OBI v0.11.0 та новіших. Він використовує структуру декларативної конфігурації OpenTelemetry. Загальні налаштування, такі як ресурси, вибірка та експортери, залишаються в корені документа, тоді як специфічні для OBI налаштування згруповані під `extensions.obi`. Якщо у вас вже є файл Config v1, використовуйте [посібник з міграції Config v1 на v2](../migrate-to-config-v2/) замість ручного переписування. ## Оберіть структуру конфігурації {#choose-a-configuration-structure} Як ви структуруєте конфігурацію, залежить від того, як ви запускаєте OBI: - **Автономний OBI**: Використовуйте повний документ декларативної конфігурації OpenTelemetry. Визначте загальні налаштування OpenTelemetry в корені документа та налаштування OBI в `extensions.obi`. - **Приймач OBI Колектора**: Визначте налаштування захоплення OBI безпосередньо під `receivers.obi`. Використовуйте конвеєр Колектора для налаштування збагачення ресурсів, обробки та експорту. ## Налаштування автономного OBI {#configure-standalone-obi} Наступний приклад інструментує один виконуваний файл і виводить захоплені відрізки у стандартний вивід для налагодження. Перед використанням цієї конфігурації в операційній діяльності замініть шлях до виконуваного файлу, видаліть `debug_trace_output` і налаштуйте OTLP-експортер під `tracer_provider`. ```yaml file_format: '1.0' extensions: obi: version: '2.0' capture: policy: default_action: exclude rules: - action: include match: process: exe_path_glob: ['/path/to/your/application'] daemon: logging: debug_trace_output: text ``` Перед запуском OBI перевірте файл конфігурації: ```sh obi config validate ./obi-v2.yaml ``` ### Структура конфігурації {#configuration-structure} ```yaml file_format: '1.0' log_level: info resource: {} tracer_provider: {} meter_provider: {} extensions: obi: version: '2.0' capture: {} enrich: {} correlation: {} daemon: {} ``` Обидва поля версії обовʼязкові, але вони ідентифікують різні схеми: - `file_format: "1.0"` ідентифікує схему декларативної конфігурації OpenTelemetry. - `extensions.obi.version: "2.0"` ідентифікує схему конфігурації OBI. Наразі `"2.0"` є єдиним підтримуваним значенням. Не встановлюйте в жодне з цих полів версію релізу OBI. ### Підтримувані поля верхнього рівня {#supported-top-level-fields} OBI v0.12.1 підтримує такі поля декларативної конфігурації OpenTelemetry: | Поле | Підтримка | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `file_format` | Обовʼязкове. Підтримуване значення — `"1.0"`. | | `log_level` | Встановлює логування OBI. Рівні trace і debug відповідають `DEBUG`; info — `INFO`; warning — `WARN`; error та fatal — `ERROR`. | | `resource` | Підтримує рядкові атрибути з іменами `host.name`, `host.id`, `service.name` та `service.namespace`. | | `tracer_provider.sampler` | Підтримує always-on, always-off, trace-ID-ratio та прості форми вибірки на базі батьківських відрізків. | | `tracer_provider.processors` | Підтримує один пакетний процесор з одним OTLP-експортером. | | `meter_provider.readers` | Підтримує щонайбільше один періодичний OTLP-читач та один Prometheus-читач для розробки (pull). | Наприклад, задайте фіксовану ідентичність сервісу з рядковими атрибутами ресурсу: ```yaml resource: attributes: - name: service.name value: checkout - name: service.namespace value: shop ``` При перевірці автономної конфігурації OBI повідомляє про помилку для непідтримуваних полів конвеєра замість їх ігнорування. У v0.12.1 не використовуйте `attribute_limits`, `instrumentation/development` або `logger_provider`. Він також відхиляє `disabled: true`, непорожній `distribution` та непорожній `propagator`. Для прикладів Config v2 OTLP/gRPC та OTLP/HTTP експортерів див. [Налаштування експортерів](../migrate-to-config-v2/#configure-exporters). Загальну інформацію про те, як OBI експортує телеметрію, див. [Налаштування експорту даних](../export-data/). ## Вибір робочих навантажень {#select-workloads} Використовуйте `capture.policy` та `capture.rules`, щоб вказати, які робочі навантаження інструментує OBI. OBI оцінює правила в порядку їх визначення. ```yaml extensions: obi: version: '2.0' capture: policy: default_action: exclude match_order: first_match_wins min_process_age: 5s rules: - action: exclude name: exclude-system-namespaces match: kubernetes: namespace_glob: ['kube-system', 'monitoring'] - action: include name: checkout-service match: process: open_ports: '8080,9090-9091' exe_path_glob: ['/srv/checkout-*'] ``` Якщо ви опускаєте `default_action`, OBI зазвичай включає робочі навантаження. Щоб інструментувати лише ті, що відповідають вашим правилам, встановіть `default_action` на `exclude` і додайте одне або кілька правил включення. Встановіть `match_order` на `first_match_wins` або `last_match_wins`. Виключення завжди мають пріоритет під час виконання. З `first_match_wins` розміщуйте правила виключення перед правилами включення. З `last_match_wins` — після. Коли ви задаєте `rules`, список замінює вбудовані виключення OBI для бінарних файлів OBI та Колектора, поширених системних просторів імен та сервісів, які вже експортують OTLP. Це також стосується `rules: []`, який видаляє всі вбудовані виключення. Зберігайте будь-які виключення, які вам все ще потрібні. Команда міграції записує ці виключення у згенерований список; залишайте їх, якщо ви не хочете їх замінити. ### Поля відповідності процесу {#process-match-fields} | Поле | Значення | | --------------------------------- | ------------------------------------------------------------------------- | | `open_ports` | Порти та діапазони через кому, наприклад `"8080,9090-9091"` | | `target_pids` | Масив ідентифікаторів процесів | | `language_glob`, `language_regex` | Відповідність мові програмування | | `cmd_args_glob`, `cmd_args_regex` | Відповідність аргументам командного рядка | | `exe_path_glob`, `exe_path_regex` | Відповідність шляху до виконуваного файлу | | `containers_only` | Відповідність лише контейнерним робочим навантаженням | | `exports_otlp` | Відповідність процесу, що експортує OTLP на заданому `port` та `protocol` | Для полів glob надайте масив значень; для полів регулярних виразів — один вираз. ### Поля відповідності Kubernetes {#kubernetes-match-fields} | Поле | Значення | | ------------------------------------------ | --------------------------------------------------- | | `namespace_glob`, `namespace_regex` | Відповідність простору імен Kubernetes | | `metadata_glob`, `metadata_regex` | Мапа полів метаданих Kubernetes для отримання збігу | | `pod_labels`, `pod_labels_regex` | Мапа міток pod для отримання збігу | | `pod_annotations`, `pod_annotations_regex` | Мапа анотацій pod для отримання збігу | Підтримувані ключі метаданих включають імена pod, deployment, ReplicaSet, DaemonSet, StatefulSet, Job, CronJob, owner та container. ### Уточнення відповідного робочого навантаження {#refine-a-matched-workload} Використовуйте блок `refine` у правилі включення, щоб перевизначити експорт сигналів та налаштування HTTP-маршрутів для відповідних робочих навантажень: ```yaml extensions: obi: version: '2.0' capture: rules: - action: include name: staging match: kubernetes: namespace_glob: ['staging-*'] refine: exports: traces: false metrics: true - action: include name: orders match: kubernetes: namespace_glob: ['orders'] refine: http: routes: incoming: patterns: ['/orders/{id}'] ignored_patterns: ['/health'] unmatched: path ``` У v0.12.1 `refine` підтримує `exports` та `http.routes`. Він не підтримує непорожнє поле `http.filters` або вибірку на рівні робочого навантаження. Налаштуйте вибірку для всіх робочих навантажень через `tracer_provider.sampler`. Коли кілька правил відповідають робочому навантаженню, правило не успадковує уточнення, які ви пропустили з попереднього правила. Якщо правила можуть перекриватися, вказуйте кожне уточнення явно і перевіряйте отриману поведінку. ## Налаштування захоплення {#configure-capture} Використовуйте `extensions.obi.capture` для налаштування того, як OBI вибирає робочі навантаження та захоплює телеметрію. Наступні налаштування можна використовувати як з автономним OBI, так і з приймачем OBI Колектора: | Розділ | Призначення | | ----------------- | ------------------------------------------------------------------------------------------------------------------- | | `policy`, `rules` | Вибір робочих навантажень та застосування уточнень на рівні робочого навантаження. | | `instrumentation` | Увімкнення та тонке налаштування протоколів застосунків. | | `runtimes` | Керування інструментуванням середовищ виконання Go, Node.js та Java. | | `network` | Налаштування захоплення мережевих потоків та TCP-статистики. | | `limits` | Встановлення обмежень кардинальності та пам'яті. | | `engine` | Тонке налаштування пакетної обробки, фільтрації PID, поширення контексту, контролю трафіку та іншої поведінки eBPF. | | `safety` | Примусове вимагання необхідних системних можливостей. | | `channels` | Тонке налаштування внутрішньої буферизації та контролю зворотного тиску. | | `telemetry` | Тонке налаштування кешів репортера OBI та утримання метрик. | ### Інструментування протоколів {#protocol-instrumentation} В `instrumentation` ви можете налаштувати HTTP, gRPC, SQL, Redis, Kafka, MongoDB, Couchbase, DNS, GPU та Aerospike інструментування. Увімкніть трейси та метрики окремо для кожного протоколу: ```yaml extensions: obi: version: '2.0' capture: instrumentation: http: enabled: traces: true metrics: true dns: enabled: traces: false metrics: true ``` Налаштуйте HTTP-маршрути окремо для вхідних та вихідних запитів. Розділи `incoming` та `outgoing` обидва приймають `patterns`, `ignored_patterns`, `ignore_mode`, `unmatched`, `wildcard_char` та `max_path_segment_cardinality`. Поведінку цих налаштувань див. у [Налаштуванні декоратора маршрутів](../routes-decorator/). Config v2 застосовує фільтри застосунків незалежно для кожного протоколу та сигналу. Наприклад, ви можете фільтрувати HTTP-трейси без застосування того самого фільтру до HTTP-метрик або SQL-телеметрії. Визначте ці фільтри під `capture.instrumentation..filters.traces` та `.metrics`. Фільтри мережевих потоків та TCP-статистики не є сигнально-специфічними у v0.12.1. Для кожної з цих груп використовуйте ту саму мапу фільтрів для трейсів та метрик. Валідація повідомляє про помилку, якщо дві мапи відрізняються. Щоб увімкнути екстракцію HTTP-навантаження, додайте екстрактори до `payload_extraction.enabled`. Підтримувані значення: `graphql`, `elasticsearch`, `aws`, `sqlpp`, `openai`, `anthropic`, `gemini`, `qwen`, `bedrock`, `mcp`, `embedding`, `rerank`, `retrieval`, `ollama`, `openai_compatible`, `jsonrpc` та `enrichment`. Використовуйте відповідний вкладений блок для налаштування увімкненого екстрактора. Вкладений блок сам по собі не вмикає екстрактор. ### Інструментування середовищ виконання {#runtime-instrumentation} Використовуйте `capture.runtimes` для увімкнення або вимкнення Go-проб, інʼєкції Node.js `SIGUSR1` та приєднання Java-агента. Ви також можете налаштувати налаштування Java debug та тайм-аут приєднання. OBI v0.12.1 не підтримує непорожні поля `filter` середовищ виконання. Використовуйте правила захоплення для вибору робочих навантажень. ### Мережева спостережуваність {#network-observability} Використовуйте `capture.network.capture` для налаштування телеметрії мережевих потоків та `capture.network.stats` для налаштування TCP-статистики. Список `features` для TCP-статистики підтримує `tcp_rtt`, `tcp_failed_connections`, `tcp_retransmits` та `tcp_io`. Увімкніть `tcp_io` лише тоді, коли вам потрібна статистика на кожне надсилання та отримання, оскільки вона може генерувати значно більше подій, ніж інші функції. Деталі розгортання та метрик див. у [Мережевій спостережуваності](../../network/). ## Налаштування функцій, доступних лише в standalone-версії {#configure-standalone-only-features} Коли ви запускаєте OBI як standalone процес, ви також можете використовувати наступні розділи під `extensions.obi`: - Використовуйте `enrich` для налаштування Kubernetes-метаданих, іменування сервісів та збагачення атрибутів. Встановіть його Kubernetes-режим на `autodetect`, `enabled` або `disabled`. - Використовуйте `correlation` для налаштування анотації контексту трасування в логах додатків. Див. [Кореляція трейсів з логами](../../trace-log-correlation/). - Використовуйте `daemon` для налаштування виводу логів, профілювання, коректного завершення роботи, внутрішніх метрик та формування Prometheus-метрик у автономному режимі. Встановіть вербальність логування через поле верхнього рівня `log_level`. ## Конфігурація приймача Колектора {#collector-receiver-configuration} У конфігурації приймача Колектора розмістіть поля, які в автономній конфігурації знаходяться під `extensions.obi.capture`, безпосередньо під `receivers.obi`, поруч з `version`. Не включайте рівень `capture`. Наприклад, наступний YAML є тілом компонента приймача OBI: ```yaml version: '2.0' policy: default_action: exclude rules: - action: include match: process: open_ports: '8080' instrumentation: http: enabled: traces: true metrics: true ``` Збережіть тіло компонента приймача у окремому файлі і перевірте його: ```sh obi config validate --mode=receiver ./obi-receiver-v2.yaml ``` Після успішної валідації скопіюйте тіло компонента під `receivers.obi` у вашій конфігурації Колектора. Потім додайте `obi` до відповідних трейс- та метрик-конвеєрів. Не додавайте до конфігурації приймача автономні розділи `enrich`, `correlation` або `daemon`. Використовуйте процесори Колектора, такі як `k8sattributes`, для збагачення, телеметрію сервісу Колектора для операційних налаштувань та експортери Колектора для експорту даних. Повне налаштування див. у [Запуск OBI як приймача Колектора](../collector-receiver/). ## Змінні середовища {#environment-variables} Коли OBI читає файл конфігурації, він розширює такі вирази змінних середовища перед парсингом YAML: - `${VAR}` та `${env:VAR}` - `${VAR:-fallback}` та `${env:VAR:-fallback}` Ви також можете використовувати еквівалентні форми `$()`. Щоб зберегти вираз як літеральний текст, додайте перед ним додатковий `$`. OBI не автоматично відображає імена змінних середовища Config v1 на поля Config v2. Щоб зберегти перевизначення середовищем, додайте вираз підстановки у відповідне поле Config v2, як описано в [Міграція перевизначень середовищем](../migrate-to-config-v2/#migrate-environment-overrides). ## Валідація конфігурації {#validate-a-configuration} Використовуйте режим валідації, що відповідає вашому розгортанню. Команда повідомляє про непідтримувані поля та конфліктні налаштування: ```sh # Standalone документ obi config validate ./obi-v2.yaml # Тіло компонента приймача obi config validate --mode=receiver ./obi-receiver-v2.yaml ``` Команда валідації не запускає OBI, не приєднує eBPF-програми, не звертається до експортера і не перевіряє ядро, яке працює. Після успішної валідації протестуйте конфігурацію у канарковому розгортанні.