このリポジトリは、OpenTelemetry Collector Processor を通じて トレースデータを追加・フィルタする設定をローカル環境で動作検証するためのリポジトリです
本番環境や共有の検証環境では、OTel Collector から組織で利用しているオブザーバビリティバックエンドにテレメトリが送信されることが想定されます。しかし、Collector の設定変更を検証するにあたり、開発したコードを毎回検証環境にデプロイし、SaaS のバックエンドで閲覧するとフィードバックループの遅さやコストの心配に悩まされることとなります。
そこで、開発者が自分のローカルマシン上で、アプリケーション用の設定値を変更することなくOTel Collector の設定を検証するための環境が必要となります。
- 本番・検証環境: App --localhost:4417--> OTel collector -> Observability Backend
- 開発マシン: App --localhost:4417--> OTel collector --localhost:4319--> otel-tui
オブザーバビリティバックエンドとしてotel-tuiを使います。デフォルト設定では、otel-tui と OTel Collector の待ち受けポートが重複してしまうため、このリポジトリでは重複を避けるための参考設定を提供しています。
計装されたアプリケーション起動時にOTEL_TRACES_EXPORTER=otlp,consoleを渡すことで、起動したターミナル上にアプリケーションが生成したトレースデータが表示されます。Collector 経由で otel-tui に送信されたトレースは、Collector の filter や insert によってスパンが増減されるはずです。この二つのスパン間の差を確認して、Collector の設定をデバッグします。
- Node.js アプリケーションの自動計装によるトレース生成
- OpenTelemetry Collector によるトレースデータの受信・処理
- otel-tui を使用したトレースデータの可視化（OTel Collector のデフォルト設定と被らない起動コマンド）
以下のツールがインストールされている必要があります：
- Node.js (v20 以上推奨)
- OpenTelemetry Collector
- otel-tui
.
├── src/
│ └── app.js # サンプルアプリケーション（HTTP fetch処理）
├── otel/
│ └── otel-collector-dev.yaml # OpenTelemetry Collectorの設定
└── package.jsonnpm installotelcol --config=otel/otel-collector-dev.yamlnpm run tuiまたは直接実行：
otel-tui --grpc 4319 --http 4320※事前に、.env.example を参考に環境変数を設定してください
OpenTelemetry 自動計装有効でアプリケーションを実行
npm run start:otel実行後、環境変数にOTEL_TRACES_EXPORTER=otlp,consoleが設定されていれば実行ターミナル上にnode.js アプリケーションによって生成されたトレースが表示されます
src/app.jsの実行により、以下のような出力が表示されます：
status: 200
data: <!doctype html>
...
中略
...
{
resource: {
attributes: {
'process.pid': xxxxx,
'process.executable.name': 'node',
...otel-tui でdeployment.collector: "col-local"が付与されたトレース情報を確認できます。これは、node アプリケーションを実行した後に表示されるトレース情報では付与されておらず、Collector の Processor で付与した属性です。
otel/otel-collector-dev.yamlでは以下を設定：
- Receivers: OTLP over gRPC (4317) / HTTP (4318)
- Processors: バッチ処理、リソース属性の追加
- Exporters: otel-tui への転送 (4319)
- otel-tui にトレースが表示されない場合は、Collector と otel-tui が正常に起動していることを確認してください
- ポート競合が発生した場合は、
otel/otel-collector-dev.yamlの設定を変更してください