OpenTelemetry

Docker Compose で OpenTelemetry Collector を実行する

マウントした設定ファイルから Collector を起動し、テストデータを送り、debug exporter で確認します。

10 min learn.level.初級

このガイドでは、YAML ファイルからローカルで Collector を実行し、トレースとメトリクスを送り、受信したものを出力します。UI では何も設定しません。Collector には UI がなく、すべてが 1 つのファイルにあります。Compose プラグインを備えた Docker と curl が必要です。

イメージを選ぶ

プロジェクトは、いくつかの Collector のディストリビューションを公開しています。core イメージ（otel/opentelemetry-collector）には、少数のコンポーネントがあります。contrib イメージ（otel/opentelemetry-collector-contrib）には、コミュニティの大きなセットが含まれ、Kubernetes 向けのイメージ（otel/opentelemetry-collector-k8s）には、クラスターの監視に必要なものが含まれます。このシリーズの後半で使う多くのコンポーネント、たとえば filelog や tail_sampling は、core イメージにありません。学習には contrib を使います。実際の使用では、これらの例のように特定のバージョンを固定し、バージョンを、使いたいリリースに置き換えてください。

プロジェクトの構成

otel-demo/
├── compose.yaml
└── otel-collector-config.yaml

Collector の設定

otel-collector-config.yaml:

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

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

上から下へ読みます。

receivers は、データの入り方を定義します。otlp は、4317 で gRPC を、4318 で HTTP をリッスンします。
processors は、転送中のデータを変更します。batch は、エクスポートを効率的にするために、項目をまとめます。
exporters は、データを外に送ります。debug は、Collector 自身のログに出力します。学習中は、これが望ましい動作です。
extensions は、パイプラインと並んで機能を追加します。health_check は、ヘルスのエンドポイントを提供します。
service は、すべてを有効にします。コンポーネントは、ここに列挙されるまで定義しても何も起こらず、各シグナルには独自のパイプラインがあります。

エンドポイントは、コンテナに外部から到達できるように、0.0.0.0 を使っています。Collector のデフォルトは localhost で、すべての送信者がローカルにいる場合はより安全なので、必要な場所でのみ 0.0.0.0 にバインドしてください。

compose ファイル

compose.yaml:

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.163.0   # テスト済みのバージョンに固定する
    command: ["--config=/etc/otelcol/config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol/config.yaml:ro
    ports:
      - "4317:4317"     # OTLP gRPC
      - "4318:4318"     # OTLP HTTP
      - "13133:13133"   # health_check
      - "8888:8888"     # Collector 自身のメトリクス

設定のパス /etc/otelcol/config.yaml は、公式イメージがデフォルトで探す場所です。他に出会うかもしれないポートは、zpages extension 用の 55679 と、Prometheus exporter 用の 8889 です。

起動前に検証する

Collector は、実行せずに設定を確認できます。

docker run --rm -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml:ro \
  otel/opentelemetry-collector-contrib:0.163.0 validate --config=/etc/otelcol/config.yaml

きれいに終了すれば、ファイルが解析でき、参照されているすべてのコンポーネントが、このディストリビューションに存在することを意味します。これを CI でも実行してください。よくある失敗は、選んだイメージにないコンポーネントを使うことです。

起動してヘルスを確認する

docker compose up -d
curl -s http://localhost:13133
docker compose logs otel-collector | tail -n 20

ヘルスのエンドポイントは小さな JSON のステータスを返し、ログには、Collector がパイプラインを開始し、4317 と 4318 でリッスンしている様子が表示されるはずです。

テスト用のテレメトリを送る

プレーンな curl で、HTTP 上の OTLP を使います。スパンを 1 つ送ります。

curl -s -X POST http://localhost:4318/v1/traces \
  -H 'Content-Type: application/json' \
  -d '{
    "resourceSpans": [{
      "resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "demo" } }] },
      "scopeSpans": [{
        "spans": [{
          "traceId": "5b8efff798038103d269b633813fc60c",
          "spanId": "eee19b7ec3c1b174",
          "name": "hello",
          "kind": 1,
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000001000000000"
        }]
      }]
    }]
  }'

レスポンスが空の JSON オブジェクトであれば、受け付けられたことを意味します。次に、Collector のログを見ます。

docker compose logs otel-collector | grep -A8 'hello'

debug exporter は、スパン、その resource（service.name: demo）、タイミングを出力します。動作するパイプラインができました。

設定を変更して再読み込みする

Collector は、起動時にファイルを読み取ります。編集後は：

docker compose restart otel-collector

このフォルダーを Git に保管してください。後のガイドでは、debug を実際の exporter に置き換え、同じファイルに processor と extension を追加します。

クリーンアップ

docker compose down

RackMint