すべての Collector の構成は、同じいくつかのルールに従う、1 つの YAML ドキュメントです。そのルールを 1 度学べば、Helm チャートや Operator に付属するものを含め、どの Collector の設定も読めるようになります。このガイドでは、構造、命名の仕組み、コンポーネントの有効化の方法、ファイルの分割とマージ、環境変数の注入を説明します。

5 つのコンポーネントの種類

セクション	役割	例
receivers	データを受け取る	otlp, prometheus, filelog, hostmetrics
processors	変換、フィルター、エンリッチ、バッチ処理	batch, memory_limiter, k8s_attributes, tail_sampling
exporters	データを送り出す	otlp, otlphttp, debug, prometheus
connectors	2 つのパイプラインを結び、一方では exporter、もう一方では receiver として動作する	spanmetrics, forward, routing
extensions	パイプラインと並んで機能を追加する	health_check, zpages, file_storage, 認証の extension

6 番目のセクション service が、それらをすべて結び付けます。

コンポーネントは service が有効にするまでオフ

これが、最もよくある混乱の元です。receiver を設定しても、それがオンになるわけではありません。コンポーネントは、service のパイプラインがそれを参照したときにのみ、効果を持ちます。

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

exporters:
  debug:
  otlp_grpc:
    endpoint: gateway.example.com:4317

service:
  extensions: [health_check, zpages]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc]
    metrics:
      receivers: [otlp]
      exporters: [otlp_grpc]
    logs:
      receivers: [otlp]
      exporters: [otlp_grpc]

定義されているが一度も参照されていないコンポーネントは無視されます。これは、ファイル内にバリエーションを保持するのに便利ですが、何も届かないときに忘れやすいものです。パイプラインの名前は traces、metrics、logs で、receiver、processor、exporter は、参加するパイプラインのシグナルをサポートしている必要があります。

命名：type と type/name

コンポーネントの識別子は、その type に、オプションで /name を続けたものです。同じ種類のコンポーネントを複数回設定するには、名前を使います。

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true
  otlp/vendor:
    endpoint: otlp.vendor.example.com:4317

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/tempo, otlp/vendor]   # 2 つのバックエンドに振り分ける

各識別子は一意である必要があります。上の振り分けは、すべてのスパンを両方の宛先に送ります。

パイプラインの詳細

• processor の順序は重要です。 データは、列挙された順序で processor を通過します。memory_limiter を最初に、batch を最後に置きます（レジリエンスのガイドを参照）。
• コンポーネントは複数のパイプラインに現れられます。 processor を使う各パイプラインは、それぞれ独自のインスタンスを得ます。
• connector はパイプラインの橋渡しをします。 connector は、あるパイプラインの exporter として、別のパイプラインの receiver として列挙されます。たとえば spanmetrics は、スパンをメトリクスに変換します。

connectors:
  spanmetrics:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/tempo, spanmetrics]
    metrics:
      receivers: [otlp, spanmetrics]
      processors: [batch]
      exporters: [otlphttp/prometheus]

環境変数

値が期待される場所ならどこでも ${env:NAME} を使い、bash 形式のデフォルトには :- を使います。

exporters:
  otlp:
    endpoint: ${env:OTLP_ENDPOINT:-gateway.example.com:4317}
    headers:
      authorization: Bearer ${env:API_TOKEN}

リテラルのドル記号を書くには、$$ を使います。シークレットは環境変数で届くため、ファイル自体はそれらを含まず、commit できます。

設定のソースとファイルのマージ

--config は、パス、または file、env、yaml、http、https のスキームを持つ scheme:value の URI を受け付けます。

otelcol --config=file:/etc/otelcol/base.yaml --config=file:/etc/otelcol/overrides.yaml
otelcol --config=env:MY_CONFIG_IN_AN_ENVVAR
otelcol --config="yaml:exporters::debug::verbosity: normal"

複数の --config オプションを渡すと、Collector はそれらを 1 つの設定にマージします。各ファイルは部分的でも構いませんが、Collector はコンポーネントを自動で追加しないため、マージ後の結果は完全である必要があります。これを使って、共有のベースファイルと、環境ごとの小さな上書きを保持します。

別のファイルを値に埋め込むこともできます。

exporters: ${file:exporters.yaml}

http と https のプロバイダーは、URL から設定を読み込みます。便利ですが、Collector の動作がそのサーバーに依存することになるため、意図的に使ってください。

検証する

otelcol validate --config=config.yaml
# または contrib イメージで
docker run --rm -v $(pwd)/config.yaml:/etc/otelcol/config.yaml:ro \
  otel/opentelemetry-collector-contrib:0.163.0 validate --config=/etc/otelcol/config.yaml

validate は、不明なコンポーネント、不正な構文、定義していないものを参照するパイプラインを検出します。バックエンドに到達できることは証明しません。

知っておくべきセキュリティのデフォルト

receiver は、デフォルトで localhost にバインドします。すべての送信者が同じホストで動作している場合は安全ですが、0.0.0.0:4317 のようなエンドポイントを設定するまで、コンテナ内の Collector が外部から到達できないことを意味します。エンドポイントをネットワークに開く場合は、TLS と認証を追加し（バックエンドのガイドを参照）、network policy やファイアウォールのルールでアクセスを制限してください。

実際のプロジェクトの読みやすいレイアウト

collector/
├── base.yaml            # receivers、processors、共有のパイプライン
├── env/
│   ├── dev.yaml         # dev 用の exporters とエンドポイント
│   └── prod.yaml
└── README.md

--config=file:base.yaml --config=file:env/prod.yaml で実行します。レビュアーは、環境ごとに何が変わるかを正確に見ることができます。

クイックリファレンス

• コンポーネントを上部に定義し、service で有効にします。
• 同じ種類のコンポーネントを繰り返すには、type/name を使います。
• processor の順序を意図的に決めます。
• 環境固有のもの、またはシークレットには、${env:VAR} を使います。
• 複数の --config ファイルをマージし、CI で validate を実行します。