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 Collector レシーバー: OBI のキャプチャ設定を receivers.obi 配下に直接定義します。 リソースエンリッチメント、処理、エクスポートの設定には Collector パイプラインを使用します。

スタンドアロン OBI の設定

以下の例では、1 つの実行可能ファイルを計装し、キャプチャしたスパンをデバッグ用に標準出力に出力します。 この設定を本番環境で使用する前に、実行可能ファイルのパスを置き換え、debug_trace_output を削除し、tracer_provider 配下に OTLP エクスポーターを設定してください。

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 に設定し、1 つ以上のインクルードルールを追加します。

match_order を first_match_wins または last_match_wins に設定します。 除外ルールは実行時に常に優先されます。 first_match_wins の場合、除外ルールをインクルードルールの前に配置します。 last_match_wins の場合、除外ルールをインクルードルールの後に配置します。

rules を設定すると、OBI および Collector バイナリ、一般的なシステム名前空間、すでに OTLP をエクスポートしているサービスに対する OBI の組み込み除外がリストに置き換わります。 これは rules: [] にも適用され、すべての組み込み除外が削除されます。 必要な除外は引き続き保持してください。 移行コマンドはこれらの除外を生成されたリストに書き込みます。 置き換える意図がない限り、それらを残しておいてください。

プロセスマッチフィールド

glob フィールドには値の配列を、正規表現フィールドには 1 つの式を指定します。

Kubernetes マッチフィールド

サポートされるメタデータキーには、Pod、Deployment、ReplicaSet、DaemonSet、StatefulSet、Job、CronJob、オーナー、およびコンテナ名が含まれます。

マッチしたワークロードの調整

インクルードルールの 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 Collector レシーバーの両方で使用できます。

プロトコル計装

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 メトリクスや SQL テレメトリーに同じフィルターを適用せずに、HTTP トレースだけをフィルタリングできます。 これらのフィルターは capture.instrumentation.<protocol>.filters.traces と .metrics 配下に定義します。

ネットワークフローフィルターと TCP 統計フィルターは v0.12.1 ではシグナル固有ではありません。 これらのグループごとに、トレースとメトリクスで同じフィルターマップを使用してください。 2 つのマップが異なる場合、検証でエラーが報告されます。

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 のデバッグ設定やアタッチメントタイムアウトも設定できます。 OBI v0.12.1 では、空でないランタイム filter フィールドはサポートされていません。 かわりにキャプチャルールを使用してワークロードを選択してください。

ネットワークオブザーバビリティ

capture.network.capture を使用してネットワークフローテレメトリーを設定し、capture.network.stats を使用して TCP 統計を設定します。 TCP 統計の features リストは tcp_rtt、tcp_failed_connections、tcp_retransmits、tcp_io をサポートします。

tcp_io は、他の機能よりも大幅に多くのイベントを生成する可能性があるため、送信ごとおよび受信ごとの統計が必要な場合にのみ有効にしてください。 デプロイメントとメトリクスの詳細については、ネットワークオブザーバビリティを参照してください。

スタンドアロン専用機能の設定

OBI をスタンドアロンプロセスとして実行する場合、extensions.obi 配下で以下のセクションも使用できます。

• enrich を使用して、Kubernetes メタデータ、サービス命名、属性エンリッチメントを設定します。 Kubernetes モードを autodetect、enabled、disabled に設定します。
• correlation を使用して、アプリケーションログにおけるトレースコンテキストアノテーションを設定します。 トレースとログの相関を参照してください。
• daemon を使用して、ログ出力、プロファイリング、グレースフルシャットダウン、内部メトリクス、スタンドアロン Prometheus メトリクスシェイピングを設定します。 ログの詳細度はトップレベルの log_level フィールドで設定します。

Collector レシーバー構成

Collector レシーバー構成では、スタンドアロン構成の extensions.obi.capture 配下にあるフィールドを、version の隣の receivers.obi 配下に直接配置します。 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

検証が成功した後、コンポーネント本体を Collector 構成の receivers.obi にコピーします。 次に、適切なトレースおよびメトリクスパイプラインに obi を追加します。

スタンドアロン専用の enrich、correlation、daemon セクションをレシーバー構成に追加しないでください。 エンリッチメントには k8sattributes などの Collector プロセッサーを、運用設定には Collector サービステレメトリーを、データエクスポートには Collector エクスポーターを使用してください。 完全なセットアップについては、OBI を Collector レシーバーとして実行するを参照してください。

環境変数

OBI が構成ファイルを読み取る際、YAML をパースする前に以下の環境変数式を展開します。

• ${VAR} および ${env:VAR}
• ${VAR:-fallback} および ${env:VAR:-fallback}

同等の $() 形式も使用できます。 式をリテラルテキストとして保持するには、先頭に $ を追加します。

OBI は Config v1 の環境変数名を Config v2 フィールドに自動的にマッピングしません。 環境変数によるオーバーライドを保持するには、環境変数オーバーライドの移行の説明に従って、対応する Config v2 フィールドに置換式を追加してください。

構成の検証

デプロイメントに合った検証モードを使用します。 コマンドはサポートされていないフィールドや競合する設定を報告します。

# スタンドアロンドキュメント
obi config validate ./obi-v2.yaml

# レシーバーコンポーネント本体
obi config validate --mode=receiver ./obi-receiver-v2.yaml

検証コマンドは OBI の起動、eBPF プログラムのアタッチ、エクスポーターへの接続、実行中のカーネルの確認を行いません。 検証が成功した後、カナリアデプロイメントで構成をテストしてください。