OTLPとは? OpenTelemetryの転送方式と設定

OTLP/gRPC と OTLP/HTTP の違い、部分成功と再試行、DataKit に送る際のエンドポイント設定を解説します。

ベストプラクティス
アプリケーション性能監視で扱うトレースとメトリクスのイメージ

Collector に接続できても、送信先のパスが違えばデータは届きません。HTTP で 200 が返っても、バッチの一部が拒否されている場合があります。切り分けには、エクスポーターが何を送ったかと、受信側が何を受け付けたかの両方を確認します。

OTLP(OpenTelemetry Protocol)は、テレメトリーのエンコードと転送を定めるプロトコルです。 メッセージを Protobuf で定義し、gRPC と HTTP に対応します。トレース、メトリクス、ログの転送仕様は安定版で、Profiles は開発段階です。送受信側が共通の信号、転送方式、エンコードを扱えるときにデータを交換できます。

OTLP の要点

  • OTLP が定めるのはデータのエンコードと転送です。保存とクエリはバックエンドが担います。
  • gRPC はバイナリの Protobuf を使います。HTTP では、受信側が対応していれば OTLP の JSON 形式も使えます。
  • Resource と計装スコープの下に、スパン、メトリクス、ログレコードがまとまります。
  • DataKit は OTLP のトレース、メトリクス、ログを受け取れます。HTTP の既定はポート 9529 と /otel/v1/ から始まるパスです。

OTLP の送信から応答まで

  1. リクエストを組み立てる。 SDK のエクスポーターや Collector が、テレメトリーを OTLP のエクスポートリクエストにまとめます。
  2. 送信する。 gRPC の単項 RPC、または HTTP の POST を使います。gzip 圧縮、TLS、認証は送受信側の設定に合わせます。
  3. 応答を読む。 完全に成功した場合、現在の受信側がバッチを受け付けています。OTLP/HTTP は、完全成功でも部分成功でも HTTP 200 を返します。partial_success が設定されていれば、拒否された件数と診断メッセージを確認します。拒否件数がゼロで警告だけが入る場合もあります。この応答を受けたリクエストは再送しません。

OTLP/HTTP では 429、502、503、504 が再試行の対象です。Retry-After があれば従い、なければ指数バックオフで再試行します。ほかの 4xx や 5xx は再試行しません。たとえば 400 なら、先にペイロードを確認します。OTLP/gRPC は gRPC のステータスとエラー詳細で判断し、UNAVAILABLE は再試行の対象です。

受領確認の範囲は、隣り合う送信側と受信側の間です。Collector が受け付けたあとに、バックエンドへの転送が失敗することもあります。応答が通信途中で失われれば、再送によって同じデータが重複して届く可能性もあります。OTLP 仕様(英語)

OTLP のデータモデル

トレース、メトリクス、ログの外側の構造は共通です。実際の Protobuf フィールド名は信号によって変わります。

Export<Signal>ServiceRequest
└── resource_<signal>[]
    ├── resource (service.name, host.name, …)
    └── scope_<signal>[]
        ├── scope (name, version, …)
        └── spans[] / metrics[] / log_records[]

スパンには trace_id、span_id、必要に応じて親スパンの ID、ステータスや属性などが入ります。メトリクスには Sum、Gauge、Histogram、ExponentialHistogram などの型があります。ログレコードには時刻、重大度、本文、属性などがあり、トレースコンテキストも含められます。

トレースの Protobuf フィールドは resource_spans、scope_spans です。OTLP の JSON 形式では traceId のように lowerCamelCase を使い、Trace ID と Span ID は16進文字列、列挙型は整数で表します。手元の JSON 生成ツールを使うときは、この形式に合うか確認します。

gRPC と HTTP の選び方

比較項目 OTLP/gRPC OTLP/HTTP
標準のデフォルトポート 4317 4318
リクエストと接続 gRPC 接続上の単項 RPC HTTP POST。接続を再利用できる
エンコード バイナリ Protobuf バイナリ Protobuf または OTLP JSON。受信側の対応次第
プロキシの要件 gRPC を正しく転送できること POST、パス、Content-Type を通せること
デバッグ 対応するサービス定義を使える gRPC クライアント curl で所定の形式のペイロードを POST

SDK、プロキシ、受信側が対応する方式を選び、運用時に使うバッチサイズや圧縮設定で、スループットとリソース消費を確認します。HTTP のバイナリ Protobuf では application/x-protobuf を使います。既定のパスは /v1/traces、/v1/metrics、/v1/logs ですが、実際の設定は受信先に合わせます。

アプリケーションから受信先へ送る

  1. アプリケーションから直接送る。 OpenTelemetry SDK(英語)や対応する自動計装を使います。エクスポーターに、受信側のプロトコルとエンドポイントを設定します。
  2. Collector を経由する。 OpenTelemetry Collector(英語)で受け取り、設定したパイプラインに従ってバッチ処理、フィルタリング、機微情報の除去などを行ってから転送します。
  3. 既存のトレース形式を変換する。 Collector のディストリビューションに Jaeger や Zipkin の receiver があれば、送信元に合うものを有効にし、OTLP でエクスポートできます。対応するプロトコルとフィールドの変換、コンテキストを確認します。

Guance に送るには DataKit の OpenTelemetry インプット(英語)と必要な信号のエクスポーターを有効にします。gRPC の設定例 127.0.0.1:4317 はループバックです。別のホストやネットワーク名前空間から送る場合は、送信元から到達できる受信アドレスを設定します。HTTP は http/protobuf を使い、既定のポートは 9529 です。パスは /otel/v1/traces、/otel/v1/metrics、/otel/v1/logs です。

以下は、信頼できるテストネットワークで平文接続を使い、DataKit の既定の HTTP パスに送る例です。ホスト名は実際の環境に置き換えます。

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://datakit-host:9529/otel

HTTP の共通エンドポイントはベース URL で、仕様に従うエクスポーターが信号ごとのパスを付けます。OTEL_EXPORTER_OTLP_TRACES_ENDPOINT のような個別設定には http://datakit-host:9529/otel/v1/traces のように完全な URL を指定します。メトリクスとログも同じです。認証は受信側やゲートウェイの要件に合わせます。送信先の Guance ワークスペースは DataKit 側の接続設定で決まります。OTLP エクスポーターの設定(英語)

識別できるテストデータを送り、意図したワークスペースで信号ごとに検索できるかを確認します。Collector のフィルタリングなどは設定どおりに送信前に行われます。ログからトレースを開くには、ID が一致し、対応するトレースが検索できる必要があります。

よくある質問

OTLP の接続はどう保護しますか? 信頼できないネットワークを通る場合は TLS を設定し、受信側の証明書を検証します。認証は構成に応じて、ゲートウェイが要求するヘッダーや mTLS などを使います。

OTLP がボトルネックになることはありますか? あります。エンコード、圧縮、ネットワーク、受信処理にそれぞれコストがかかります。バッチを大きくするとリクエストのオーバーヘッドは減らせますが、待ち時間やメモリ使用量が増える場合があります。gzip で通信量を減らす場合も CPU を使います。送信遅延、キュー使用量、拒否件数を確認しながら調整します。

新しいエクスポーターから古い受信側へ送れますか? Protobuf は、未認識のフィールドを無視できるなど、一部のスキーマ変更に互換性があります。使いたい信号、エンコード、オプション機能は両端が対応している必要があります。

OTLP のバックエンドを Guance に統一できますか? 必要な信号と処理を DataKit の連携で扱える場合は、Guance に送れます。クエリ、保存、アラートに必要なデータが信号ごとにそろうかを確認します。

関連記事

参考資料 OTLP 仕様(英語) · Guance の OpenTelemetry 連携(英語) · DataKit 文書(英語) · Guance APM

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ