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

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

計装の互換性

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

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

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

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

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

GPU 計装の互換性

OBI は、環境が OBI 互換性要件 を満たし、アプリケーションがサポート対象の CUDA ランタイムライブラリを使用している場合に GPU 計装をサポートします。

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

GPU 計装は、上記のサポート対象 CUDA ランタイムライブラリと操作を使用するアプリケーションにのみ適用されます。 他の GPU API、フレームワーク、ライブラリは、特に記載がない限りサポート対象外です。

メトリクスの共通設定

YAML セクションは metrics です。

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

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

次がその例です。

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

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

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

• all または *: すべてのメトリクスグループ（すべてのメトリクスを有効にする便利なオプション）
• application: アプリケーションレベルのメトリクス。
• application_host: ホストベースの価格設定向けのアプリケーションレベルのホストメトリクス。
• application_span: レガシー形式（traces_spanmetrics_latency など）のアプリケーションレベルのトレーススパンメトリクス。spanmetrics は独立していません。
• application_span_otel: OpenTelemetry 形式（traces_span_metrics_calls_total など）のアプリケーションレベルのトレーススパンメトリクス。span_metrics は独立しています。
• application_span_sizes: リクエストとレスポンスのサイズ情報を報告するアプリケーションレベルのトレーススパンメトリクス。
• application_service_graph: アプリケーションレベルのサービスグラフメトリクス。 サービスディスカバリーには DNS を使用し、DNS 名が OBI で使用される OpenTelemetry サービス名と一致するようにすることを推奨します。 Kubernetes 環境では、サービス名ディスカバリーで設定された OpenTelemetry サービス名がサービスグラフメトリクスに最適です。
• network: ネットワークレベルのメトリクス。詳細については、ネットワークメトリクス の設定ドキュメントを参照してください。
• network_inter_zone: ネットワークのゾーン間メトリクス。詳細については、ネットワークメトリクス の設定ドキュメントを参照してください。

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

また、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

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

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

プロトコルを設定しない場合、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）
• couchbase: memcached プロトコルに基づく Couchbase N1QL/SQL++ クエリメトリクスおよび KV（Key-Value）プロトコルメトリクス
• genai: GenAI クライアントメトリクス（OpenAI、Anthropic、Gemini、AWS Bedrock）
• gpu: GPU パフォーマンスメトリクス
• mongo: MongoDB クライアント呼び出しメトリクス
• dns: DNS クエリメトリクス

たとえば、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）
• couchbase: Couchbase N1QL/SQL++ クエリトレースおよび KV（Key-Value）プロトコルトレース（クエリテキストと操作の詳細を含む）
• genai: GenAI クライアントトレース（OpenAI、Anthropic、Gemini、AWS Bedrock）
• gpu: GPU パフォーマンストレース
• mongo: MongoDB クライアント呼び出しトレース
• dns: DNS クエリトレース

たとえば、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 パブリッシュ/サブスクライブメッセージメトリクス
• couchbase: Couchbase N1QL/SQL++ クエリメトリクスおよび KV プロトコルメトリクス
• genai: GenAI クライアントメトリクス（OpenAI、Anthropic、Gemini、AWS Bedrock）

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