OBI の Prometheus および OpenTelemetry データエクスポート設定

OBI は OpenTelemetry 形式のメトリクスとトレースを OTLP エンドポイントにエクスポートできます。

計装の互換性

OBI はトレースとメトリクスの計装において、以下のプロトコルと機能バージョンをサポートします。

一部のアプリケーションレベルの計装は、特定のランタイム、ライブラリ、またはサーバーのバージョンにも依存します。

Go ライブラリの計装互換性

OBI はアプリケーション計装において、以下の Go ライブラリと最低バージョンをサポートします。

これらの表に記載されているバージョンは、OBI が明示的にサポートするバージョンです。 他のバージョンでも動作する場合がありますが、特に記載がない限りサポート対象外です。

ベクトル検索ペイロードの解析を有効にするには、ebpf.payload_extraction.http.genai.retrieval.enabled: true または OTEL_EBPF_HTTP_RETRIEVAL_ENABLED=true を設定します。 サポートされる API には Pinecone、Qdrant、Milvus および Zilliz、Chroma、Weaviate があります。 ペイロード解析にはゼロでない ebpf.buffer_sizes.http 値も必要です。 v0.10.0 では、リクエスト方向あたりの HTTP キャプチャサイズは最大 262144 バイトです。キャプチャはデフォルトで無効です。

GPU 計装の互換性

OBI は、環境が OBI 互換性要件 を満たし、アプリケーションがサポート対象の CUDA ランタイムまたはドライバーライブラリを使用している場合に GPU 計装をサポートします。 GPU モニタリングはアプリケーションの GPU ワークを報告するもので、GPU 使用率や温度などのデバイスヘルスメトリクスは対象外です。

OBI は以下の CUDA 操作を計装します。

OBI はメモリ、ストリーム、イベント、デバイスイントロスペクションの一部の呼び出しも監視します。 API の完全なリストとメトリクスについては、v0.15.2 GPU モニタリングリファレンス を参照してください。

メトリクスの共通設定

YAML セクションは metrics です。

metrics セクションには、OpenTelemetry メトリクスとトレースのエクスポーターに共通の設定が含まれます。

現在、エクスポートするメトリクスのセットを選択できます。

次がその例です。

metrics:
  features: ['network', 'network_inter_zone']

メトリクスのエクスポート機能

OBI メトリクスエクスポーターは、メトリクスディスカバリーの設定でエントリーと一致するプロセスに対して、以下のメトリクスデータグループをエクスポートできます。

• all または *: すべてのメトリクスグループ（すべてのメトリクスを有効にする便利なオプション）
• application: アプリケーションレベルの RED メトリクスおよび HTTP ボディサイズヒストグラム。
• application_red: HTTP ボディサイズヒストグラムを含まないアプリケーションレベルの RED メトリクス。
• application_sizes: HTTP リクエストおよびレスポンスのボディサイズヒストグラム。 application_red と組み合わせて使用します。application_sizes 単独では無効です。
• application_runtime: 計装対象のサービスから収集される Go、JVM、.NET、Node.js、Python のランタイムメトリクス。 ランタイムメトリクス を参照してください。
• application_span: 非推奨のレガシー形式（traces_spanmetrics_latency など）のアプリケーションレベルのトレーススパンメトリクス。spanmetrics は独立していません。
• application_span_otel: OpenTelemetry 形式（traces.span.metrics.calls など）のアプリケーションレベルのトレーススパンメトリクス。span_metrics は独立しています。
• application_span_sizes: 非推奨のリクエストとレスポンスのサイズを報告するアプリケーションレベルのトレーススパンメトリクス。
• application_service_graph: アプリケーションレベルのサービスグラフメトリクス。 サービスディスカバリーには DNS を使用し、DNS 名が OBI で使用される OpenTelemetry サービス名と一致するようにすることを推奨します。 Kubernetes 環境では、サービス名ディスカバリーで設定された OpenTelemetry サービス名がサービスグラフメトリクスに最適です。
• network: ネットワークレベルのメトリクス。詳細については、ネットワークメトリクス の設定ドキュメントを参照してください。
• network_flow_packets: ネットワークパケットカウンターメトリクス。詳細については、ネットワークメトリクス の設定ドキュメントを参照してください。
• network_inter_zone: ネットワークのゾーン間メトリクス。詳細については、ネットワークメトリクス の設定ドキュメントを参照してください。
• stats: すべての TCP 統計メトリクス。
• stats_tcp_rtt: TCP ラウンドトリップタイムヒストグラムメトリクス。
• stats_tcp_failed_connections: TCP 接続失敗カウンターメトリクス。失敗理由でラベル付けされます。
• stats_tcp_successful_connections: TCP 接続成功カウンターメトリクス。
• stats_tcp_retransmits: TCP 再送カウンターメトリクス。
• stats_tcp_io: ソケットレイヤーで転送された TCP バイト数。I/O 方向でラベル付けされます。 この機能はすべての TCP 送受信呼び出しを監視するため、他の stats 機能よりもオーバーヘッドが高くなる可能性があります。
• ebpf: ロードされたプローブとマップの eBPF ランタイムメトリクス。Prometheus エクスポーターおよび内部メトリクスレポーターを通じて公開されます。

application バンドルには HTTP ボディサイズヒストグラムが含まれます。 ヒストグラムなしで RED メトリクスのみを使用するには、metrics.features: [application_red] を設定します。 サービスが discovery.instrument[].metrics.features を設定する場合、両方が必要なときは application_red と application_sizes を合わせて指定してください。

アプリケーション別のメトリクスエクスポート機能

また、OBI では discovery > instrument の各エントリーに metrics > features プロパティを追加することで、アプリケーションごとにグローバルなメトリクスエクスポート機能を上書きできます。

たとえば、以下の設定では次のようになります。

• apache、nginx、tomcat サービスインスタンスは、トップレベルの metrics > features 設定で定義された application_service_graph メトリクスのみをエクスポートします。

• pyserver サービスは application グループのメトリクスのみをエクスポートします。

• ポート 3030 または 3040 でリッスンしているサービスは、application、application_span、application_service_graph のメトリクスグループをエクスポートします。

metrics:
  features: ['application_service_graph']
discovery:
  instrument:
    - open_ports: 3030,3040
      metrics:
        features:
          - 'application'
          - 'application_span'
          - 'application_service_graph'
    - name: pyserver
      open_ports: 7773
      metrics:
        features:
          - 'application'
    - name: apache
      open_ports: 8080
    - name: nginx
      open_ports: 8085
    - name: tomcat
      open_ports: 8090

ランタイムメトリクス

OBI は、対象プロセスに SDK の変更を必要とせずにランタイムメトリクスを収集できます。

Go、JVM、.NET、Node.js、Python のランタイムメトリクスを有効にするには、application_runtime メトリクス機能を使用します。 Go のランタイム値は対象がガベージコレクションサイクルを完了した後に報告されるため、新しいプロセスではこれらのメトリクスがすぐには発行されない場合があります。 GOGC、GOMEMLIMIT、GOMAXPROCS の変更は、次のサイクル完了後に反映されます。

Node.js では、OBI はイベントループの時間、使用率、および遅延を 1 秒ごとにサンプリングします。 イベントループの時間と使用率には Node.js 14.10 以降が必要です。 遅延メトリクスには Node.js 16.14 以降が必要です。 OBI はメインスレッドのイベントループのみを報告し、OBI がランタイムメトリクスエージェントを注入するにはインスペクターが到達可能である必要があります。

Linux 上の .NET 8 以降では、OBI はプロセスの診断ソケットを通じてランタイムメトリクスを収集します。 診断を有効にし、OBI が対象プロセスのファイルシステムを通じてソケットにアクセスできるようにしてください。 v0.15.2 でプロセッサー数、プロセス CPU 時間、最後のコレクションのヒープサイズが追加されました。 デフォルトのポーリング間隔は 1 秒で、dotnet_runtime_metrics.sampling_interval で設定します。 診断 IPC のセットアップとシャットダウンには dotnet_runtime_metrics.timeout（デフォルト 10s）を使用します。 収集のセマンティクスとメトリクスの可用性については、.NET ランタイムリファレンス を参照してください。

HotSpot JVM メモリメトリクスの OBI サンプリング間隔を制御するには、jvm_runtime_metrics.sampling_interval を使用します。

metrics:
  features: [application_runtime]
jvm_runtime_metrics:
  sampling_interval: 1s

OpenTelemetry メトリクスエクスポーターコンポーネント

YAML セクションは otel_metrics_export です。

設定ファイルでエンドポイント属性を設定するか、環境変数を使用して OpenTelemetry メトリクスエクスポートコンポーネントを有効にします。 メトリクスエクスポート設定オプション を参照してください。

YAML 設定の otel_metrics_export セクション、または環境変数でコンポーネントを設定します。

この記事に記載されている設定に加えて、標準 OpenTelemetry エクスポーター設定 の環境変数もサポートします。

次は設定例です。

otel_metrics_export:
  ttl: 5m
  endpoint: http://otelcol:4318
  protocol: grpc
  buckets:
    duration_histogram: [0, 1, 2]
  histogram_aggregation: base2_exponential_bucket_histogram

メトリクスのエクスポートプロトコル

メトリクスエクスポーターは HTTP 経由で protobuf を送信します。 Config v1 は http/json を受け付けますが、メトリクスは protobuf として送信され警告がログに記録されます。 JSON エンコーディングはトレースのみでサポートされています。

プロトコルを設定しない場合、OBI は以下のようにプロトコルを設定します。

• grpc: ポートが 4317 で終わる場合（例: 4317、14317、24317）。
• http/protobuf: ポートが 4318 で終わる場合（例: 4318、14318、24318）。

メトリクスの計装

OBI がデータを収集できる計装領域のリストは以下のとおりです。

• *: すべての計装。* が存在する場合、OBI は他の値を無視します
• http: HTTP/HTTPS/HTTP/2 アプリケーションメトリクス
• grpc: gRPC アプリケーションメトリクス
• sql: SQL データベースクライアント呼び出しメトリクス（PostgreSQL、MySQL、pgx などの Go database/sql ドライバーを含む）
• redis: Redis クライアント/サーバーデータベースメトリクス
• kafka: Kafka クライアント/サーバーメッセージキューメトリクス
• mqtt: MQTT パブリッシュ/サブスクライブメッセージメトリクス（MQTT 3.1.1 および 5.0）
• nats: NATS パブリッシュ/サブスクライブメッセージメトリクス
• amqp: AMQP 1.0 パブリッシュ/プロセスメッセージメトリクス
• couchbase: memcached プロトコルに基づく Couchbase N1QL/SQL++ クエリメトリクスおよび KV（Key-Value）プロトコルメトリクス
• memcached: Memcached ASCII プロトコルメトリクス
• genai: GenAI クライアントメトリクス（OpenAI、Anthropic、Gemini、AWS Bedrock、Qwen、MCP、およびサポートされている embedding API、rerank API、ベクトル検索 API）
• gpu: GPU パフォーマンスメトリクス
• mongo: MongoDB クライアント呼び出しメトリクス
• dns: DNS クエリメトリクス
• sunrpc: TCP 上の ONC RPC クライアントおよびサーバーメトリクス

たとえば、instrumentations オプションを http,grpc に設定すると、HTTP/HTTPS/HTTP2 および gRPC アプリケーションメトリクスの収集が有効になり、他の計装は無効になります。

OpenTelemetry トレースエクスポーターコンポーネント

YAML セクションは otel_traces_export です。

YAML 設定の otel_traces_export セクション、または環境変数でコンポーネントを設定できます。

この記事に記載されている設定に加えて、標準 OpenTelemetry エクスポーター設定 の環境変数もサポートします。

otel_traces_export:
  endpoint: http://jaeger:4317
  protocol: grpc
  instrumentations: ['http', 'sql']

トレースのエクスポートプロトコル

プロトコルを設定しない場合、OBI は以下のようにプロトコルを設定します。

• grpc: ポートが 4317 で終わる場合（例: 4317、14317、24317）。
• http/protobuf: ポートが 4318 で終わる場合（例: 4318、14318、24318）。

トレースの計装

OBI がデータを収集できる計装領域のリストは以下のとおりです。

• *: すべての計装。* が存在する場合、OBI は他の値を無視します
• http: HTTP/HTTPS/HTTP/2 アプリケーショントレース
• grpc: gRPC アプリケーショントレース
• sql: SQL データベースクライアント呼び出しメトリクス（PostgreSQL、MySQL、pgx などの Go database/sql ドライバーを含む）
• redis: Redis クライアント/サーバーデータベーストレース
• kafka: Kafka クライアント/サーバーメッセージキュートレース
• mqtt: MQTT パブリッシュ/サブスクライブメッセージトレース（MQTT 3.1.1 および 5.0）
• nats: NATS パブリッシュ/サブスクライブメッセージトレース
• amqp: AMQP 1.0 パブリッシュ/プロセスメッセージトレース
• couchbase: Couchbase N1QL/SQL++ クエリトレースおよび KV（Key-Value）プロトコルトレース（クエリテキストと操作の詳細を含む）
• memcached: Memcached ASCII プロトコルトレース
• genai: GenAI クライアントトレース（OpenAI、Anthropic、Gemini、AWS Bedrock、Qwen、MCP、およびサポートされている embedding API、rerank API、ベクトル検索 API）
• gpu: GPU パフォーマンストレース
• mongo: MongoDB クライアント呼び出しトレース
• dns: DNS クエリトレース
• sunrpc: TCP 上の ONC RPC クライアントおよびサーバートレース

たとえば、instrumentations オプションを http,grpc に設定すると、HTTP/HTTPS/HTTP2 および gRPC アプリケーショントレースの収集が有効になり、他の計装は無効になります。

MQTT 計装

OBI は MQTT 通信を自動的に計装します。MQTT は IoT や組み込みシステムで一般的に使用される軽量メッセージングプロトコルです。

サポートされる操作

• publish: トピックへのメッセージ送信
• subscribe: トピックのサブスクリプション要求

プロトコルバージョン

• MQTT 3.1.1
• MQTT 5.0

キャプチャされる情報

• トピック名（サブスクライブ操作では最初のトピックフィルターのみ）
• 操作レイテンシ
• クライアント-サーバー通信パターン

制限事項

• サブスクライブ操作では最初のトピックフィルターのみがキャプチャされます
• オーバーヘッドを最小限に抑えるため、メッセージペイロードはキャプチャされません

ユースケース例: センサーデータを MQTT ブローカーにパブリッシュする IoT ゲートウェイを監視し、メッセージ配信率を追跡して通信の問題を特定します。

PostgreSQL pgx ドライバー計装

OBI は、PostgreSQL データベース向けの高性能なネイティブ Go ドライバーである pgx に特化した計装を提供します。

pgx の特徴: pgx 計装は Go 専用の eBPF トレーシングを使用して Go ドライバーに直接フックし、汎用ネットワークレベルの SQL 計装のオーバーヘッドなしにデータベース固有のオブザーバビリティを提供します。

サポートされる操作

• Query: 結果セットを伴う SQL クエリ実行
• 接続プーリング（pgxpool を使用）
• ネイティブ pgx API および database/SQL ラッパーインターフェイス

キャプチャされる情報

• SQL クエリテキスト
• PostgreSQL サーバーホスト名（pgx 接続設定から取得）
• 操作時間とエラーの詳細
• すべての標準 database/SQL メトリクスラベル

サポートされる pgx バージョン: pgx v5.0.0 以降（v5.8.0 まで検証済み）。database/SQL ラッパー経由でもサポートされます: github.com/jackc/pgx/v5/stdlib

Couchbase 計装

Couchbase は、直接 Key-Value アクセスと SQL++ による SQL ライクなクエリの両方をサポートする NoSQL ドキュメントデータベースです。 柔軟なスキーマと高可用性が求められるアプリケーションで一般的に使用されています。 OBI は 2 つのプロトコルを通じて Couchbase 操作を計装します。

• KV（Key-Value）プロトコル: ポート 11210 での直接 Key-Value アクセスのためのバイナリプロトコル。Memcached バイナリプロトコル の拡張に基づいています。
• SQL++（N1QL）: ポート 8093 の /query/service エンドポイントを使用する HTTP ベースのクエリプロトコル。

KV（Key-Value）プロトコル

キャプチャされる情報:

バケット、スコープ、コレクションのトラッキング: Couchbase は階層的な名前空間を使用します: Bucket → Scope → Collection。 リクエストごとの名前空間プロトコルとは異なり、名前空間は接続レベルで確立されます。

• SELECT_BUCKET（トレース対象外）: 接続上の後続の操作すべてにアクティブなバケットを設定します。MySQL の USE database や Redis の SELECT db_number に相当します。
• GET_COLLECTION_ID（トレース対象外）: scope.collection パスを数値のコレクション ID に解決します。OBI はこれを使用してスコープ名とコレクション名でスパン属性を補完します。

OBI は接続ごとにバケット名、スコープ名、コレクション名のキャッシュを管理し、後続のすべてのスパンにアノテーションを付けるために使用します。

制限事項

• SELECT_BUCKET が OBI 起動前に発生した場合、その接続のバケット名は不明です
• GET_COLLECTION_ID が OBI 起動前に発生した場合、コレクション名は利用できません
• 認証とメタデータ操作はキャプチャされません
• これらの制限は OBI 初期化前に確立された接続のみに影響します

SQL++（N1QL）操作

SQL++ クエリ（N1QL クエリ言語の最新名称）は、ポート 8093 の /query/service エンドポイントにある Couchbase の HTTP クエリサービスを通じて自動的に検出されます。

サポートされる操作

• すべての SQL++ クエリタイプ: SELECT、INSERT、UPDATE、DELETE、UPSERT
• SQL パス（例: bucket.scope.collection）を通じてアクセスするバケットおよびコレクション操作
• コレクション間およびバケット間クエリ

キャプチャされる情報

サポートされるデータベース

• Couchbase Server: レスポンスの N1QL バージョンヘッダーで検出
• その他の SQL++ 実装: Apache AsterixDB および互換データベースも汎用の other_sql 指定でサポートされています

リクエスト形式: SQL++ リクエストは JSON ボディと /query/service へのフォームエンコードされた POST の両形式を受け付けます。

• JSON Body
• Form Encoded

{
  "statement": "SELECT * FROM `bucket`.`scope`.`collection` WHERE id = $1",
  "query_context": "default:`bucket`.`scope`"
}

statement=SELECT+*+FROM+users&query_context=default:`travel-sample`.`inventory`

名前空間の解決: パーサーは以下からバケットとコレクションを抽出します。

1. SQL ステートメントのテーブルパス: `bucket`.`scope`.`collection`
2. 存在する場合の query_context フィールド
3. 単一識別子: コレクション名として扱われます（query_context あり）またはバケット名として扱われます（query_context なし、レガシーモード）

設定: SQL++ 計装には明示的な有効化が必要です。

export OTEL_EBPF_HTTP_SQLPP_ENABLED=true
export OTEL_EBPF_BPF_BUFFER_SIZE_HTTP=2048  # Larger than default; needed to capture request/response bodies

制限事項

• バケットとコレクションの検出には、クエリ内の SQL パス表記（例: bucket.scope.collection）またはリクエストの query_context フィールドが必要です
• Couchbase バージョンヘッダーのないレスポンスは汎用の other_sql 操作としてラベル付けされます

ユースケース例: セッションストレージとコンテンツ管理に Couchbase を使用する高トラフィックな Web アプリケーションを監視し、クエリパフォーマンスを追跡して非効率な N1QL クエリを特定します。

Prometheus エクスポーターコンポーネント

YAML セクションは prometheus_export です。

YAML 設定の prometheus_export セクション、または環境変数でコンポーネントを設定できます。 このコンポーネントは自動計装ツールに HTTP エンドポイントを開き、外部のスクレイパーが Prometheus 形式でメトリクスをプルできるようにします。 port プロパティが設定されている場合に有効になります。

prometheus_export:
  port: 8999
  path: /metrics
  extra_resource_attributes: ['deployment_environment']
  ttl: 1s
  buckets:
    request_size_histogram: [0, 10, 20, 22]
    response_size_histogram: [0, 10, 20, 22]
  instrumentations: ['http', 'sql']

Prometheus の追加リソース属性

Prometheus API クライアントの内部的な制限により、OBI は各メトリクスに対してどの属性が公開されるかを事前に把握する必要があります。 このため、計装中にランタイムで検出される一部の属性はデフォルトでは表示されません。 たとえば、Kubernetes アノテーションを通じて各アプリケーションで定義された属性や、対象アプリケーションの OTEL_RESOURCE_ATTRIBUTES 環境変数で定義された属性などです。

たとえば、アプリケーションが OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production を環境変数として定義している場合、target_info{deployment.environment="production"} 属性は、メトリクスが OpenTelemetry 経由でエクスポートされる場合はデフォルトで表示されますが、Prometheus 経由の場合は表示されません。

deployment_environment を Prometheus で表示するには、extra_resource_attributes リストに追加する必要があります。

Prometheus 計装

OBI がデータを収集できる計装領域のリストは以下のとおりです。

• *: すべての計装。* が存在する場合、OBI は他の値を無視します
• http: HTTP/HTTPS/HTTP/2 アプリケーションメトリクス
• grpc: gRPC アプリケーションメトリクス
• sql: SQL データベースクライアント呼び出しメトリクス（PostgreSQL、MySQL、pgx などの Go database/sql ドライバーを含む）
• redis: Redis クライアント/サーバーデータベースメトリクス
• kafka: Kafka クライアント/サーバーメッセージキューメトリクス
• mqtt: MQTT パブリッシュ/サブスクライブメッセージメトリクス
• nats: NATS パブリッシュ/サブスクライブメッセージメトリクス
• amqp: AMQP 1.0 パブリッシュ/プロセスメッセージメトリクス
• couchbase: Couchbase N1QL/SQL++ クエリメトリクスおよび KV プロトコルメトリクス
• memcached: Memcached ASCII プロトコルメトリクス
• genai: GenAI クライアントメトリクス（OpenAI、Anthropic、Gemini、AWS Bedrock、Qwen、MCP、およびサポートされている embedding API、rerank API、ベクトル検索 API）
• gpu: GPU パフォーマンスメトリクス
• mongo: MongoDB クライアント呼び出しメトリクス
• dns: DNS クエリメトリクス
• sunrpc: TCP 上の ONC RPC クライアントおよびサーバーメトリクス

たとえば、instrumentations オプションを http,grpc に設定すると、HTTP/HTTPS/HTTP2 および gRPC アプリケーションメトリクスの収集が有効になり、他の計装は無効になります。