OpenTelemetry Collector導入ガイド - インストールから起動確認まで
分散システムのテレメトリデータを管理するには、アプリケーションから監視バックエンドまで、安定した流れを作る必要があります。OpenTelemetry Collectorは、その流れの中心的な役割を担うコンポーネントです。このガイドでは、Collectorの役割を理解し、実際にインストール・起動確認するまでの流れを一緒に学んでいきましょう。
OpenTelemetry Collectorの役割と重要性
OpenTelemetry Collectorは、アプリケーションから送信されるテレメトリデータ（トレース、メトリクス、ログ）を受け取り、処理してから監視バックエンドに送信するコンポーネントです。単なる中継ツールではなく、データの品質を高め、システム全体の効率を改善する重要な役割を果たします。
Collectorが必要な理由
アプリケーションが直接監視バックエンドにデータを送信することもできますが、本番環境ではCollectorを導入することをお勧めします。なぜなら、Collectorがあると、アプリケーションはデータを素早く送信して、その後の処理はCollectorに任せられるからです。Collectorは、ネットワーク障害時の再試行、データのバッチ処理、暗号化、そしてデータのフィルタリングなど、複雑な処理を担当します。
Collectorの基本アーキテクチャ
Collectorは3つの主要なコンポーネントで構成されています。
Receiver（レシーバー） アプリケーションやシステムからテレメトリデータを受け取ります。ネットワークポートでデータをリッスンするタイプと、外部システムを定期的にスクレイピングしてデータを取得するタイプがあります。OTLPやJaeger、Prometheusなど、様々な形式をサポートしています。
Processor（プロセッサー） 受け取ったテレメトリデータを加工・変換します。属性の追加や削除、サンプリング（一部のデータのみを処理対象にする）、バッチ処理など、様々な操作が可能です。本番環境ではパフォーマンスとコスト効率を両立させるのに役立ちます。
Exporter（エクスポーター） 処理されたテレメトリデータを監視バックエンドに送信します。Jaeger、Prometheus、Datadog、New Relic、AWS X-Rayなど、多くのバックエンドをサポートしています。
この3つのコンポーネントが組み合わさって、「パイプライン」を形成します。
Collectorのデプロイメント方式
Collectorは2つの主な方式でデプロイできます。
Agent方式 Collectorが各サーバーやコンテナ内で動作し、そのマシン上のアプリケーションから直接データを受け取ります。Kubernetesではサイドカーとして動作させることが多いです。この方式は、各アプリケーションの近くでデータを処理できるため、レイテンシー（遅延）を低く保つメリットがあります。
Gateway方式 Collectorが中央のサービスとして動作し、複数のアプリケーションやAgentから送信されたデータを受け取ります。この方式は、全体的なテレメトリデータを一箇所で管理でき、フィルタリングやルーティングなど複雑な処理を一元化できます。
多くの場合、Agent方式とGateway方式の両方を組み合わせて使用します。
Collectorのインストール方法
Collectorはさまざまな環境にインストールできます。使用環境と要件に応じて、最適なインストール方法を選択しましょう。
Docker（最も簡単な方法）
開発環境やラボ環境の場合、Dockerを使うのが最も簡単です。dockerコマンド一行でCollectorを起動できます。
docker pull otel/opentelemetry-collector-contrib:0.103.1
docker run -p 127.0.0.1:4317:4317 -p 127.0.0.1:4318:4318 \
-p 127.0.0.1:13133:13133 -p 127.0.0.1:55679:55679 \
otel/opentelemetry-collector-contrib:0.103.1Dockerを使うメリットは、複雑な設定なしにすぐに試せることです。デメリットは、本番環境でのカスタマイズに限界がある点です。
バイナリのダウンロード（Linux/macOS/Windows）
公式リポジトリからバイナリをダウンロードして直接実行する方法です。Linux、macOS、Windowsで利用でき、AMD64、ARM64、i386などのアーキテクチャに対応しています。
Linuxの場合は、まずバイナリをダウンロードして実行権限を付与します。その後、アプリケーションと同じディレクトリに配置したり、システムのPATHに追加したりして使用します。
パッケージマネージャー（DEB/RPM）
Linuxの場合、DEB形式やRPM形式のパッケージが提供されており、通常のパッケージマネージャーでインストールできます。例えば、Ubuntu/Debianであればaptコマンド、CentOS/RHELであればyumコマンドで取得します。
この方法でインストールすると、デフォルトで設定ファイルが/etc/otelcol/config.yamlに配置され、systemdサービスとして自動起動のセットアップが行われます。本番環境での使用に最も適しています。
インストール方法の選択基準
| 方法 | 用途 | 利点 | 注意点 |
|---|---|---|---|
| Docker | 開発・検証 | セットアップが簡単、すぐに試せる | カスタム設定を使う場合はボリュームマウント必要 |
| バイナリ | 開発・小規模本番 | 柔軟にカスタマイズ可能 | 手動でのセットアップが必要 |
| パッケージ | 本番環境 | systemd統合、自動起動対応 | Linuxのみ利用可能 |
Dockerで設定ファイルを使いたい場合の例
カスタム設定ファイル（config.yaml）をCollectorで使う場合は、ボリュームマウントオプション（-v）を使用します。
docker run -p 127.0.0.1:4317:4317 -p 127.0.0.1:4318:4318 \
-p 127.0.0.1:13133:13133 -p 127.0.0.1:55679:55679 \
-v ./config.yaml:/etc/otelcol-contrib/config.yaml \
otel/opentelemetry-collector-contrib:0.103.1この例では、カレントディレクトリのconfig.yamlファイルをコンテナ内の/etc/otelcol-contrib/config.yamlにマウントしています。
基本的な起動確認
Collectorが正常に動作しているか確認するための方法をいくつか紹介します。
Dockerでの起動確認
前のセクションのDockerコマンドを実行した後、別のターミナルウィンドウで以下のコマンドを実行して、Collectorが正常に起動していることを確認します。
コンテナの状態確認
docker psこのコマンドで、実行中のコンテナ一覧が表示されます。otel/opentelemetry-collector-contribという名前のコンテナがUp状態になっていることを確認しましょう。
ログの確認
docker logs <container_id><container_id>は、上記のdocker psコマンドで表示されるコンテナIDに置き換えてください。Collectorのログが表示され、起動時のメッセージやエラーがないか確認できます。
ヘルスチェック
Collectorは起動時に自動でヘルスチェック機能を有効にしています。別のターミナルウィンドウで次のコマンドを実行して、Collectorが正常に動作しているか確認できます。
curl http://localhost:13133/healthzレスポンスがOKまたは200 OKであれば、Collectorは正常に動作しています。
ログの確認
ターミナルに表示されるログを見て、エラーがないか確認しましょう。Collectorが正常に起動すると、以下のような情報が表示されます。
- Receiverが正常に起動したというメッセージ
- リッスンしているポート番号
- Processorの状態
- Exporterの接続状態
エラーメッセージが表示されている場合、それがなぜ発生しているのか、次のセクションで確認しましょう。
ZPagesでの動作確認
Collectorはデバッグ用のWebページを提供しています。ブラウザでhttp://localhost:55679/debug/tracezにアクセスすると、受け取ったテレメトリデータの処理状況をリアルタイムで確認できます。これは、Collectorが正常にデータを受け取り、処理しているかを確認するのに役立ちます。
初期トラブルシューティング
Collectorのインストール後、よくある問題と対処方法を紹介します。
ポート番号の競合
Collectorがリッスンするポート（4317や4318など）が既に別のアプリケーションで使用されていると、起動に失敗します。このような場合は、別のポート番号を使うか、既存のアプリケーションを停止する必要があります。
Linux/macOSではlsof -i :4317コマンドで、どのプロセスがそのポートを使用しているか確認できます。Windowsではnetstat -ano | findstr :4317コマンドを使用します。
アプリケーションからの接続エラー
アプリケーションがCollectorに接続できない場合、設定ファイルのポート番号がアプリケーション側の設定と一致しているか確認しましょう。また、ファイアウォール設定によって通信がブロックされていないかも確認が必要です。
設定ファイルの読み込みエラー
Collectorは起動時に設定ファイル（config.yaml）を読み込みます。YAMLの構文エラー（インデント不正、コロンの位置ズレなど）があるとエラーメッセージが表示されます。エラーメッセージをよく読んで、どの行に問題があるのか特定しましょう。
まとめ
OpenTelemetry Collectorは、テレメトリデータの流れを管理する重要なコンポーネントです。開発環境ではDocker、本番環境ではパッケージマネージャーでのインストールが適切です。インストール後は、必ずヘルスチェックとZPagesで正常に動作しているか確認する習慣をつけましょう。
このガイドで紹介したインストール方法と確認手順を通じて、Collectorの基本的な使い方が理解できたはずです。次は、Collectorの設定方法についてさらに詳しく学んでいきます。