OpenTelemetry Collectorの設定を開発環境でデバッグするにはotel-tuiが便利
OpenTelemetry計装の動作確認、毎回クラウド側で確認してませんか？
皆さん、こんにちは。Splunk Observability Solutions Architectの髙柴です。
オブザーバビリティを導入する際、開発者の皆さんから「計装コードや設定が正しく動いているかどうか確認するのに時間がかかる」「本番やステージング環境にデプロイしないと結果が分からないのはつらい」という声をよく聞きます。
この記事では、ローカルに閉じた状態で開発者フレンドリーなテレメトリデータを確認する方法を紹介します。
よくある課題感
Splunk Observability Cloudをはじめとするクラウドサービスにデータを送信し、ダッシュボードやトレース一覧への反映を待ってから確認するワークフローでは、時間がかかる上にサービスの利用料金が心配事としてついて回ります。
ローカル環境でJaegerやGrafanaのようなバックエンドをローカル起動してもよいですが、単純なテレメトリデータ確認以外の機能も付いてきますし、可視化までにデータインデックス処理などを経由すると、確認まで若干のレイテンシも発生します。単機能でシンプルな解決策が欲しいところです。
そんな課題を解決してくれるのが otel-tui です。このツールを使うことで、軽量なTUI(ターミナル・ユーザー・インターフェース)でOpenTelemetryのテレメトリーデータをリアルタイムに確認でき、開発体験を大幅に向上させることができます。TUIアプリということもあって、ブラウザと行き来する必要がないのも便利です。
otel-tui とは
otel-tuiは、OpenTelemetryのテレメトリーデータをターミナル上でリアルタイムに可視化できるTUIアプリケーションです。
なお、このツールの作者は日本人の@ymtdzzzさんで、作者本人の方がリリース時に紹介記事をZennに書かれています。
otel-tuiを使うことで、ローカルで即座にテレメトリーデータの出力内容を確認できます。起動も軽量で、TUIツールの特性上IDEの開発環境上ですべてを確認できることもメリットです。
実際の使用例
私が作成したサンプルリポジトリで実際に動作させた例を示します。
OpenTelemetry Collectorのプロセッサーを使い、 属性を追加(insert)したり、フィルターやサンプリングをしてバックエンドへのデータ送信量を減らしたりしたいケースを想定しています。
先述の通り、このような場合に特定の環境までリリースしないと変更結果が分からないようでは、不必要にステージング用ブランチにプッシュしたり、デプロイ待ちが発生したりと非効率的です。また、本番環境を汚すことにもなりかねません。
実現したい構成
アプリケーションの設定を変更することなく、Collectorの処理（フィルタリング、属性のinsertなど）をローカルで検証可能にすることを目指します。
ローカルでは下記のようにlocalhost内で完結させますが、本番環境をはじめとする構成では、otel-tuiの代わりにオブザーバビリティバックエンドが同じ位置に入ります。
- 本番・検証環境: App --localhost:4317--> OTel Collector -> オブザーバビリティバックエンド
- 開発マシン: App --localhost:4317--> OTel Collector --localhost:4319--> otel-tui
アプリケーションから出力されるテレメトリーデータと、otel-tuiで確認できるテレメトリーデータを比較することで、OTel Collectorのプロセッサーの動作確認を行います。
では、さっそく手順を見ていきましょう。
前提として、サンプルリポジトリはクローン済みで、OTel Collectorは手元の開発環境にインストール済みとします。
OpenTelemetry Collector の設定（ローカル）
ローカル環境用のOTel Collectorの設定ファイルである otel-collector-dev.yaml がリポジトリの中に含まれています。
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317 # 本番環境と同じポートを設定してアプリケーションの変更を不要に
http:
endpoint: 0.0.0.0:4318
processors:
batch:
timeout: 1s
send_batch_size: 100
send_batch_max_size: 512
resource/dev:
attributes:
- key: deployment.collector
value: "col-local"
action: insert
exporters:
otlp/tui:
endpoint: localhost:4319
tls:
insecure: true
sending_queue:
queue_size: 1000
retry_on_failure:
enabled: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [resource/dev, batch]
exporters: [otlp/tui]
extensions: []
telemetry:
metrics:
readers:
- pull:
exporter:
prometheus:
host: "0.0.0.0"
port: 8889 # collector自身のメトリクス公開はotel-tuiと重複させない
意図通り動作すれば、processors.resource/dev.attributes で定義している属性がotel-tui上だけで確認できるはずです。
起動手順
計装アプリ用の環境変数をあらかじめ設定しておきます。方法はなんでもかまいません。
OTEL_TRACES_EXPORTER=console を設定することで、実行しているターミナル上でアプリケーションが直接出力しているテレメトリーデータを確認できます。
OTEL_TRACES_EXPORTER=otlp,console
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=sample-app
ポートが重複しないようにCollectorとotel-tuiを起動し、アプリケーションを実行してトレースデータを生成します。
# 1. OpenTelemetry Collectorを起動
# 公式手順通りにCollectorをインストールすると、デフォルト設定で起動済みなので、一度停止しておく※Ubuntuの例
sudo systemctl disable otelcol
sudo systemctl stop otelcol
otelcol --config=otel-collector-dev.yaml
# 2. otel-tuiを別ポートで起動（別ターミナル）
otel-tui --grpc 4319 --http 4320
# 3. アプリケーション実行（別ターミナル）
npm i
node -r @opentelemetry/auto-instrumentations/register app.js
検証のポイント
ここまで実行すると、2つの出力を比較してCollectorの動作を確認できます。
-
アプリケーション出力（
OTEL_TRACES_EXPORTER=console）：- アプリケーションを実行したコンソールで元のトレースデータ（Collector処理前）を確認
-
otel-tui 画面：
- Collectorで処理されたトレースデータを確認
-
deployment.collector: "col-local"などの追加属性を確認
TUI での確認
otel-tuiを起動すると、以下のような画面でリアルタイムにトレースを確認できます。
- トレース一覧: 受信したトレースがリアルタイムで表示
- スパン詳細: 選択したトレースのスパン階層を表示
- 属性確認: 各スパンの属性やタグを詳細表示
- フィルタリング: サービス名、オペレーション名での絞り込み
これだけではCollectorを経由して出力したトレースのみを表示しているので、アプリケーション側の実行結果も並べます。
Collectorのプロセッサーで追加された属性であるdeployment.collector: "col-local" がotel-tuiのみに表示され、アプリケーション側のターミナルには表示されていることが分かります（文字が小さくすみません）
これにより、Collector による属性追加が正しく動作していることを確認できます。
トラブルシューティング
otel-tui にトレースが表示されない
症状: otel-tuiを起動してもトレースが表示されない。
確認ポイント:
- OpenTelemetry Collectorが正常に起動していることを確認
- otel-tuiが正しいポートで起動していることを確認（
--grpc 4319） - アプリケーションが正しいエンドポイントに送信していることを確認
# Collectorのログを確認
otelcol --config=otel-collector-dev.yaml --verbosity=DEBUG
# ポート使用状況を確認
lsof -i :4317 -i :4319
ポート競合エラー
症状: address already in use エラーが発生。
解決方法:
- 使用中のプロセスを確認して停止するか、別のポートを使用
- 設定ファイルでポート番号を変更
# ポート使用状況確認
netstat -tulpn | grep :4317
# プロセス終了
kill -9 <PID>
Collector の設定が反映されない
症状: 属性追加などのプロセッサーが動作しない。
確認ポイント:
- YAML設定ファイルの文法エラーチェック
- プロセッサーの順序確認
- サービスパイプラインの設定確認
- Collectorの再起動
リリースまでの流れ
otel-tuiでローカル検証が完了したら、デプロイ先の環境ではその環境用のOpenTelemetryの設定ファイルを利用します。これにより、Splunk Observability Cloudをはじめとするオブザーバビリティバックエンドにトレースやメトリクスを送信できます。
テレメトリデータは最終的に、オブザーバビリティバックエンドで可視化されるわけですが、その可視化層がotel-tuiから契約しているSaaSに入れ替わるイメージです。開発環境での検証と本番環境での運用が同じアプリケーションコードで実現できる点が最大のメリットです。変更が必要なのは、Collectorの設定だけです。
まとめ
otel-tuiは、OpenTelemetryを活用した開発において、以下の価値を提供します。
- 高速なフィードバックループ: デプロイやバックエンドのGUI反映を待たずに設定変更を検証
- オフライン開発: インターネット接続不要
Splunk と OpenTelemetry
オブザーバビリティツールを扱う際、OpenTelemetryを採用するメリットの1つは、豊富なエコシステムを活用できることです。今回紹介したotel-tuiやOTelBinのような便利なツールを扱うことができ、ナレッジも豊富に蓄積されるため、特定のベンダーに依存した計装を行うよりも開発生産性をあげやすいことが期待されます。
また、OpenTelemetryエコシステムには以下のような利点があります。
- ベンダー中立性: 特定のベンダーに依存しない標準化されたフォーマット
- 豊富な言語サポート: Java、Python、Go、Node.js、.NETなど主要言語をカバー
- 柔軟な計装オプション: 自動計装から手動計装まで、要件に応じて選択可能
現在、OpenTelemetryはCloud Native Computing Foundation(CNCF)においてKubernetesに次ぐコントリビューター数（全体で2位）を誇るプロジェクトとなっています。
OpenTelemetryを採用していれば、将来に特定のオブザーバビリティバックエンドを利用しなくなった場合でも、開発環境やテレメトリーの取得構成はそのままに、Collectorのコンフィグを変更することでオブザーバビリティバックエンドのみを変更できます。
Splunk は、OpenTelemetry に対して多く貢献している企業で、提供しているサービスであるSplunk Observability CloudもOpenTelemetryに完全準拠しています。
「オブザーバビリティを始めたい！」という方は、ぜひ、OpenTelemetryを使ってアプリケーションの計装を試してみることをおすすめします。
参考リンク
Discussion