OpenTelemetry eBPF 計装

自動計装に OpenTelemetry eBPF 計装を使用する方法を学びます。

OpenTelemetry ライブラリは、一般的なプログラミング言語やフレームワーク向けのテレメトリー収集機能を提供します。 しかし、分散トレーシングの導入は複雑になる場合があります。 Go や Rust などの一部のコンパイル型言語では、コードにトレースポイントを手動で追加する必要があります。

OpenTelemetry eBPF 計装(OBI)は、アプリケーションのオブザーバビリティを簡単に開始するための自動計装ツールです。 OBI は eBPF を使用して、アプリケーションの実行可能ファイルと OS ネットワーク層を自動的に検査し、サポートされた Linux ワークロードのトレーススパン、Rate Errors Duration(RED)指標、ランタイム指標、アプリケーションおよびネットワークの関係をキャプチャします。 すべてのデータキャプチャは、アプリケーションのコードや構成を変更することなく行われます。

OBI は以下の機能を提供します。

  • 幅広い言語サポート: Java(JDK 8+)、.NET、Go、Python、Ruby、Node.js、C、C++、および Rust
  • 軽量: コード変更不要、ライブラリインストール不要、再起動不要
  • 効率的な計装: トレースとメトリクスは、最小限のオーバーヘッドで eBPF プローブによってキャプチャ
  • 分散トレーシング: 分散トレーススパンがキャプチャされ、Collector に送信される
  • ログエンリッチメント: JSON およびプレーンテキストのログをトレースコンテキストでエンリッチしてトレースと相関させる
  • Kubernetes ネイティブ: Kubernetes アプリケーションに構成不要の自動計装を提供
  • 暗号化された通信の可視性: TLS/SSL 経由のトランザクションを復号化せずにキャプチャ
  • コンテキスト伝搬: サービス間でトレースコンテキストを自動的に伝搬
  • プロトコルサポート(クライアントおよびサーバー): HTTP/S、HTTP/2、gRPC、Kafka、NATS、MQTT、Memcached、SunRPC(NFS を含む)、および JSON-RPC
  • プロトコルサポート(クライアントのみ): AMQP 1.0 および DNS クエリ
  • データベース計装(クライアントおよびサーバー): PostgreSQL(pgx ドライバーを含む)、MySQL、MSSQL、および Redis
  • データベース計装(クライアントのみ): MongoDB、Couchbase(N1QL/SQL++ および KV プロトコル)、Aerospike、Elasticsearch、および OpenSearch
  • HTTP ペイロード計装: サーバーサイドの GraphQL とクライアントサイドの Elasticsearch、OpenSearch、および AWS S3、SQS、SNS、さらにクライアントとサーバーの両方での MCP over JSON-RPC
  • 生成 AI 計装: OpenAI、OpenAI 互換ゲートウェイ、Ollama、Anthropic Claude、Google AI Studio(Gemini)、AWS Bedrock、Qwen(DashScope)、MCP over JSON-RPC、埋め込みおよび再ランク API、およびベクトル検索システムのトレースとメトリクス
  • ランタイムメトリクス: SDK を変更せずに Go、JVM、.NET、Node.js、および Python のランタイムメトリクスを収集
  • GPU 計装: Linux でサポートされた CUDA ランタイムオペレーションをキャプチャ
  • スパンおよびサービスグラフメトリクス: アプリケーションのスパンメトリクスとサービス間の関係をエクスポート
  • 低カーディナリティメトリクス: コスト削減のための低カーディナリティの Prometheus 互換メトリクス
  • ネットワークのオブザーバビリティ: バイトおよびパケットカウンター、TCP RTT、再送、接続、ソケット I/O メトリクスとともにサービス間のネットワークフローをキャプチャ
  • 強化されたサービスディスカバリー: DNS 解決によるサービス名の検索の改善
  • Collector との統合: OBI を OpenTelemetry Collector レシーバーコンポーネントとして実行

安定性

OBI v1.0.0 は最初の安定リリースです。 以下の互換性を保証します。

  • go.opentelemetry.io/obi のパブリック Go API。
  • Config v2、その生成スキーマ、および OpenTelemetry 宣言的設定のサポートされたサブセット。
  • ドキュメント化された CLI フラグ、環境変数、リリースバイナリ、およびコンテナイメージの動作。
  • OTLP と組み込み Prometheus 出力の両方で stable に分類されたテレメトリー。
  • サポートされた環境、およびドキュメント化されたアップグレードと非推奨のルール。

これらの保証を破る変更には新しいメジャーバージョンが必要です。 マイナーリリースは互換性のある機能を追加でき、パッチリリースは互換性を維持します。 リリースノートとバージョニングポリシーを参照してください。

コレクターレシーバーは v0 リリースラインで個別にバージョン管理されています。 stable とマークされていないテレメトリーと属性は引き続き変更される可能性があり、セマンティック規約の整合が進められている間はネットワークフロー属性名も同様です。 テレメトリーの安定性を参照してください。

v1.0.0 へのアップグレード

  • Config v2 を使用してください。 Config v1 は引き続きサポートされますが、バグ修正や新機能は提供されません。 移行ガイドに従い、移行された設定をロールアウト前に1つのインスタンスでテストしてください。
  • コレクターレシーバーは v0.15.2 のままです。 コアの v1.0.0 は個別に選択してください。 コレクターレシーバーのセットアップを参照してください。
  • テレメトリースキーマ URL は 0.15.2 から 1.0.0 に変更されます。 スキーマは以前の変換を保持し、新しいリネームは追加されません。 スキーマの制限についてはテレメトリーの安定性を参照してください。

v1.0.0-rc.1 または v0.15.2 より前のリリースからアップグレードする場合は、v0.15.2 リリースノートでスパン名、デフォルトのメトリクス属性、Prometheus ラベル、および Go 設定 API の変更を確認してください。 v0.14.0 より前のリリースからアップグレードする場合は、v0.14.0 リリースノートも確認してください。 ロールアウト中は既知の運用上の制限事項を確認してください。

上流のサンプルを確認するには、 NGINX ウォークスルーと Apache ウォークスルーを参照してください。

OBI の仕組み

以下の図は、OBI の高レベルアーキテクチャと、eBPF 計装がテレメトリーパイプラインにどのように適合するかを示しています。

OBI eBPF architecture

互換性

OBI は、以下の要件を満たす Linux 環境をサポートしています。

要件サポート対象
CPU アーキテクチャamd64、arm64
Linux カーネル5.8+、または必要な eBPF バックポートが適用された RHEL ファミリーのカーネルバージョン 4.18+ の Linux
カーネル機能BTF
権限Root、または有効化された OBI 機能に必要な Linux ケーパビリティ

OBI は以下のサポートされたリリース成果物を公開しています。

成果物サポートされるプラットフォーム
obi バイナリアーカイブLinux amd64, Linux arm64
otel/ebpf-instrument コンテナイメージLinux amd64, Linux arm64
otel/opentelemetry-ebpf-k8s-cache コンテナイメージLinux amd64, Linux arm64

OBI は、要件を満たす環境であれば、スタンドアロン Linux ホスト、コンテナ、および Kubernetes にデプロイできます。

サポートマトリクスで、サポートされた環境と機能固有の要件を定義しています。

OBI は、Linux 以外のオペレーティングシステム、amd64 および arm64 以外の Linux アーキテクチャ、BTF のない Linux 環境、またはドキュメントに示されている 4.18+ の RHEL ファミリーという例外を除き、Linux 5.8 より古いカーネルバージョンをサポートしていません。

機能固有のサポートの詳細については、以下のガイドに記載されています。

制限事項

OBI は、コード変更なしにアプリケーションとプロトコルのオブザーバビリティを提供しますが、すべてのシナリオで言語レベルの計装を置き換えるものではありません。 カスタムスパン、アプリケーション固有の属性、ビジネスイベント、または eBPF ベースの計装が自動的に取得できないその他のインプロセステレメトリーが必要な場合は、言語エージェントまたは手動による計装を使用してください。

OBI はネットワークとプロトコルのアクティビティを自動的にキャプチャできますが、eBPF 観測ポイントから見えないアプリケーション固有の詳細を常に復元できるわけではありません。

一部の機能には、コアプラットフォーム要件よりも追加の注意事項やサポート範囲の制限があります。 詳細については、分散トレースとエクスポートされた計装の機能固有のドキュメントを参照してください。

既知の制限事項と未解決の報告には以下が含まれます。

OBI が必要とするケーパビリティの包括的なリストについては、セキュリティ、権限、およびケーパビリティを参照してください。

OBI を使い始める

トラブルシューティング


OBI の構成

OBI の構成方法を学びます。

ネットワークメトリクス

OBI をポイントツーポイントのネットワークメトリクスの観察用に設定する

OBIをセットアップする

OBIのセットアップと実行方法を学びます。

OBI がエクスポートするメトリクス

OBI がエクスポートできる HTTP/gRPC メトリクスについて学びます。

OBI のセキュリティ、権限、ケーパビリティ

OBI が必要とする権限とケーパビリティ

トラブルシューティング

OBI の一般的な問題やエラーのトラブルシューティング

サービス時間ではなくリクエスト全体の時間を計測する

クライアント側から見たリクエスト全体の時間を計測する方法

OBI による分散トレース

OBI の分散トレースサポートについて学びます。

OBI と Cilium の互換性

OBI を Cilium と並行して実行する際の互換性に関する注意事項

OBI におけるトレースコンテキストの関連付け

分散トレースのために、OBI が送信リクエストを受信した親リクエストにどのように関連付けるかを学びます。

OBI メトリクスのカーディナリティ

計装される環境のサイズと複雑さを考慮した、デフォルトの OBI インストールで生成されるメトリクスのカーディナリティの算出方法の概要。

トレースとログの相関

より迅速なデバッグとトラブルシューティングのために、OBI がアプリケーションログを分散トレースとどのように相関付けるかを学びます。