Довідка по OBI Config v2

Config v2 доступний у OBI v0.11.0 та новіших. Він використовує структуру декларативної конфігурації OpenTelemetry. Загальні налаштування, такі як ресурси, вибірка та експортери, залишаються в корені документа, тоді як специфічні для OBI налаштування згруповані під extensions.obi.

Якщо у вас вже є файл Config v1, використовуйте посібник з міграції Config v1 на v2 замість ручного переписування.

Оберіть структуру конфігурації

Як ви структуруєте конфігурацію, залежить від того, як ви запускаєте OBI:

• Автономний OBI: Використовуйте повний документ декларативної конфігурації OpenTelemetry. Визначте загальні налаштування OpenTelemetry в корені документа та налаштування OBI в extensions.obi.
• Приймач OBI Колектора: Визначте налаштування захоплення OBI безпосередньо під receivers.obi. Використовуйте конвеєр Колектора для налаштування збагачення ресурсів, обробки та експорту.

Налаштування автономного OBI

Наступний приклад інструментує один виконуваний файл і виводить захоплені відрізки у стандартний вивід для налагодження. Перед використанням цієї конфігурації в операційній діяльності замініть шлях до виконуваного файлу, видаліть debug_trace_output і налаштуйте OTLP-експортер під tracer_provider.

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 перевірте файл конфігурації:

obi config validate ./obi-v2.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.

Підтримувані поля верхнього рівня

OBI v0.12.1 підтримує такі поля декларативної конфігурації OpenTelemetry:

Наприклад, задайте фіксовану ідентичність сервісу з рядковими атрибутами ресурсу:

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 експортерів див. Налаштування експортерів. Загальну інформацію про те, як OBI експортує телеметрію, див. Налаштування експорту даних.

Вибір робочих навантажень

Використовуйте capture.policy та capture.rules, щоб вказати, які робочі навантаження інструментує OBI. OBI оцінює правила в порядку їх визначення.

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: [], який видаляє всі вбудовані виключення. Зберігайте будь-які виключення, які вам все ще потрібні. Команда міграції записує ці виключення у згенерований список; залишайте їх, якщо ви не хочете їх замінити.

Поля відповідності процесу

Для полів glob надайте масив значень; для полів регулярних виразів — один вираз.

Поля відповідності Kubernetes

Підтримувані ключі метаданих включають імена pod, deployment, ReplicaSet, DaemonSet, StatefulSet, Job, CronJob, owner та container.

Уточнення відповідного робочого навантаження

Використовуйте блок refine у правилі включення, щоб перевизначити експорт сигналів та налаштування HTTP-маршрутів для відповідних робочих навантажень:

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.

Коли кілька правил відповідають робочому навантаженню, правило не успадковує уточнення, які ви пропустили з попереднього правила. Якщо правила можуть перекриватися, вказуйте кожне уточнення явно і перевіряйте отриману поведінку.

Налаштування захоплення

Використовуйте extensions.obi.capture для налаштування того, як OBI вибирає робочі навантаження та захоплює телеметрію. Наступні налаштування можна використовувати як з автономним OBI, так і з приймачем OBI Колектора:

Інструментування протоколів

В instrumentation ви можете налаштувати HTTP, gRPC, SQL, Redis, Kafka, MongoDB, Couchbase, DNS, GPU та Aerospike інструментування. Увімкніть трейси та метрики окремо для кожного протоколу:

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. Поведінку цих налаштувань див. у Налаштуванні декоратора маршрутів.

Config v2 застосовує фільтри застосунків незалежно для кожного протоколу та сигналу. Наприклад, ви можете фільтрувати HTTP-трейси без застосування того самого фільтру до HTTP-метрик або SQL-телеметрії. Визначте ці фільтри під capture.instrumentation.<protocol>.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. Використовуйте відповідний вкладений блок для налаштування увімкненого екстрактора. Вкладений блок сам по собі не вмикає екстрактор.

Інструментування середовищ виконання

Використовуйте capture.runtimes для увімкнення або вимкнення Go-проб, інʼєкції Node.js SIGUSR1 та приєднання Java-агента. Ви також можете налаштувати налаштування Java debug та тайм-аут приєднання. OBI v0.12.1 не підтримує непорожні поля filter середовищ виконання. Використовуйте правила захоплення для вибору робочих навантажень.

Мережева спостережуваність

Використовуйте capture.network.capture для налаштування телеметрії мережевих потоків та capture.network.stats для налаштування TCP-статистики. Список features для TCP-статистики підтримує tcp_rtt, tcp_failed_connections, tcp_retransmits та tcp_io.

Увімкніть tcp_io лише тоді, коли вам потрібна статистика на кожне надсилання та отримання, оскільки вона може генерувати значно більше подій, ніж інші функції. Деталі розгортання та метрик див. у Мережевій спостережуваності.

Налаштування функцій, доступних лише в standalone-версії

Коли ви запускаєте OBI як standalone процес, ви також можете використовувати наступні розділи під extensions.obi:

• Використовуйте enrich для налаштування Kubernetes-метаданих, іменування сервісів та збагачення атрибутів. Встановіть його Kubernetes-режим на autodetect, enabled або disabled.
• Використовуйте correlation для налаштування анотації контексту трасування в логах додатків. Див. Кореляція трейсів з логами.
• Використовуйте daemon для налаштування виводу логів, профілювання, коректного завершення роботи, внутрішніх метрик та формування Prometheus-метрик у автономному режимі. Встановіть вербальність логування через поле верхнього рівня log_level.

Конфігурація приймача Колектора

У конфігурації приймача Колектора розмістіть поля, які в автономній конфігурації знаходяться під extensions.obi.capture, безпосередньо під receivers.obi, поруч з version. Не включайте рівень capture. Наприклад, наступний YAML є тілом компонента приймача OBI:

version: '2.0'
policy:
  default_action: exclude
rules:
  - action: include
    match:
      process:
        open_ports: '8080'
instrumentation:
  http:
    enabled:
      traces: true
      metrics: true

Збережіть тіло компонента приймача у окремому файлі і перевірте його:

obi config validate --mode=receiver ./obi-receiver-v2.yaml

Після успішної валідації скопіюйте тіло компонента під receivers.obi у вашій конфігурації Колектора. Потім додайте obi до відповідних трейс- та метрик-конвеєрів.

Не додавайте до конфігурації приймача автономні розділи enrich, correlation або daemon. Використовуйте процесори Колектора, такі як k8sattributes, для збагачення, телеметрію сервісу Колектора для операційних налаштувань та експортери Колектора для експорту даних. Повне налаштування див. у Запуск OBI як приймача Колектора.

Змінні середовища

Коли OBI читає файл конфігурації, він розширює такі вирази змінних середовища перед парсингом YAML:

• ${VAR} та ${env:VAR}
• ${VAR:-fallback} та ${env:VAR:-fallback}

Ви також можете використовувати еквівалентні форми $(). Щоб зберегти вираз як літеральний текст, додайте перед ним додатковий $.

OBI не автоматично відображає імена змінних середовища Config v1 на поля Config v2. Щоб зберегти перевизначення середовищем, додайте вираз підстановки у відповідне поле Config v2, як описано в Міграція перевизначень середовищем.

Валідація конфігурації

Використовуйте режим валідації, що відповідає вашому розгортанню. Команда повідомляє про непідтримувані поля та конфліктні налаштування:

# Standalone документ
obi config validate ./obi-v2.yaml

# Тіло компонента приймача
obi config validate --mode=receiver ./obi-receiver-v2.yaml

Команда валідації не запускає OBI, не приєднує eBPF-програми, не звертається до експортера і не перевіряє ядро, яке працює. Після успішної валідації протестуйте конфігурацію у канарковому розгортанні.