はじめに

OpenTelemetryを活用した分散トレーシングやメトリクス収集が広がる中、OTLP/HTTP通信の内容を詳細に確認したいという場面がちょいちょいあります。

例えばさくらのクラウドのモニタリングスイートというサービスではログをOTLP/HTTPで送信可能です。

manual.sakura.ad.jp

このモニタリングスイートと連携する時にどのようなリクエストを送っているのかだとかレスポンスの具体的な内容だとかを確認したいケースがあったりします。

これを簡単に行うためにOTLP/HTTPでのリクエスト/レスポンスを可視化する軽量プロキシツール otlp-http-spy というのを作ったのでご紹介します。

`otlp-http-spy`とは？

otlp-http-spyは、OpenTelemetry Protocol (OTLP) のHTTP通信を監視し、リクエストとレスポンスの内容を人間が読みやすいJSON形式で標準出力に表示する軽量なHTTPプロキシです。これにより、OTLP/HTTPを利用したログ、トレース、メトリクスのデータフローを容易にデバッグできます。

主な特徴は以下の通りです：

OTLP/HTTPエンドポイントのサポート：/v1/logs、/v1/traces、/v1/metrics に対応
ProtobufペイロードのJSON変換：バイナリ形式のProtobufデータをJSONに変換し、内容を可視化
リクエストとレスポンスのロギング：HTTPヘッダーとボディの両方を詳細に記録
上流エンドポイントへの転送：受信したリクエストを指定したバックエンドに転送
環境変数による設定：動作設定を環境変数で簡単に変更可能
軽量なDockerイメージ：マルチアーキテクチャ対応のDockerイメージを提供

GitHub：https://github.com/yamamoto-febc/otlp-http-spy

github.com

なぜ作ったの?

=== 2024/04/01 : WHYを書いてなかったので追記

OpenTelemetry Collectorもエスクポート時のエラーくらいは表示してくれているのですが、例えば以下のような表示でどのようなエラーかは表示してくれずでした。

otel-collector-1  | 2025-03-31T01:39:13.094Z error   exporterhelper/retry_sender.go:145  Exporting failed. The error is not retryable. Dropping data.    {"kind": "exporter", "data_type": "logs", "name": "otlphttp", "error": "Permanent error: error exporting items, request to (バックエンドのURL)/v1/logs responded with HTTP Status Code 500", "dropped_items": 1}

上記の場合実はバックエンド側で↓のようなエラーが出ている状況だったのですがここから気づくのは無理ゲーでした... (以下の出力はotlp-http-spyからの出力)

=== Forwarded Response Headers ===

HTTP/2.0 500 Internal Server Error
Content-Length: 57
Content-Type: text/plain; charset=UTF-8
Date: Mon, 31 Mar 2025 01:39:13 GMT
(中略)

=== Raw Response ===

Unknown error: Timestamp is too old. 1970-01-01T00:00:00Z

OpenTelemetry Collectorが詳細なエラー出力をしてくれれば良いのですが、現時点ではOTLP/HTTPエクスポーターはエクスポーターがどのようなリクエスト/レスポンスをやりとりしたのかを出力する術を持っていないようでした。最初はOTLP/HTTPエクスポーターのHTTPクライアントのTransportにリクエスト/レスポンスをダンプするようなRoundTripperを噛ませようとしたのですが、OTLP/HTTPエクスポーターのコードに手を入れるよりは別途プロキシを作った方が楽という判断でした。

=== 2024/04/01追記ここまで

OpenTelemetry Collectorとの連携例

otlp-http-spy を OTLP/HTTPを受け付けるバックエンドの前段に挟むことで、バックエンドに送られる前のOTLP/HTTPリクエストやレスポンスを可視化できます。

[アプリケーション]
       |
       v
[OpenTelemetry Collector]
       |
       v
[otlp-http-spy]  ←★ リクエストをログにダンプ
       |
       v
[モニタリングスイートなどのOTLP/HTTPを受け付けるバックエンド]

この構成では、アプリケーションは OTLP/gRPCなどでOpenTelemetry Collectorにエクスポートし、OpenTelemetry Collectorがotlp-http-spy に対しOTLP/HTTP でエクスポート、otlp-http-spy はそのリクエストをダンプしつつバックエンドにフォワードします。

Collectorの設定例

Collector 側では、通常の otlp receiver を使い、Exporter に otlp-http-spy を示すために otlphttp/spy というエイリアス名を使うと分かりやすくなります。

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:

exporters:
  debug:
    verbosity: detailed
  otlphttp/spy:
    endpoint: http://localhost:4318
    compression: none

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: []
      exporters: [debug, otlphttp/spy]

    metrics:
      receivers: [otlp]
      processors: []
      exporters: [debug, otlphttp/spy]

    logs:
      receivers: [otlp]
      processors: []
      exporters: [debug, otlphttp/spy]

インストールと実行方法

Dockerを使用する場合

docker run --rm -p 4318:4318 -e ENDPOINT=https://your-otlp-http-backend ghcr.io/yamamoto-febc/otlp-http-spy:latest

GitHub Releasesからダウンロードする場合

以下から任意のプラットフォーム向けの実行ファイルをダウンロード

github.com

ENDPOINT=https://your-otlp-http-backend  otlp-http-spy

go installする場合

go install github.com/yamamoto-febc/otlp-http-spy@latest

ENDPOINT=https://your-otlp-http-backend  otlp-http-spy

ログ出力例

===> Received OTLP request:  /v1/logs

=== HTTP Request Headers ===
POST /v1/logs HTTP/1.1
Host: localhost:4318
Content-Type: application/x-protobuf

=== OTLP Message (Request) ===

{
  "resourceLogs": [
    ...
  ]
}

=== Forwarded Response Headers ===
HTTP/1.1 200 OK
Content-Type: application/x-protobuf

=== OTLP Message (Response) ===

{
  "partialSuccess": {
    "rejectedLogRecords": 0
  }
}

おわりに

otlp-http-spyは、OTLP/HTTP通信の内容を詳細に確認し、OpenTelemetryのデバッグを効率化するためのツールです。OTLP/HTTPでの通信を人が読める形でダンプすることでOpenTelemetry Collectorやバックエンドが受け取る前のリクエストやレスポンスを直接観察できます。開発中のプロジェクトではありますが、実用性のある最小限の機能がすでに利用可能です。

ぜひ試してみて、フィードバックなどお寄せください！

github.com