Collector は 1 つのバイナリですが、いくつかの形で実行できます。どれが適しているかは、サービスの数、必要な処理の量、インフラを誰が所有しているかによります。このガイドでは、そのパターンを説明し、最も一般的なもの、つまり、ノードレベルのエージェントが中央のゲートウェイに転送する構成の設定を示します。

パターン

Collector なし。 アプリケーションは、OTLP をバックエンドに直接エクスポートします。最もシンプルな構成で、追加で実行するものは何もなく、プロトタイプには問題ありません。欠点：すべてのアプリケーションがバックエンドのアドレスと認証情報を必要とし、宛先を変更するにはアプリケーションの再デプロイが必要で、フィルター、マスキング、サンプリングを行う中央の場所がありません。

エージェント。 Collector が、ワークロードの隣で実行されます。サイドカーとして、またはノードごとに 1 つ（Kubernetes の DaemonSet）です。アプリケーションは localhost やノードに送信するため、エクスポートは高速で、アプリケーションのネットワークパスは短くなります。エージェントは、ホストとノードのメトリクス、ローカルのファイルからのログ収集、ローカルのメタデータによるデータのエンリッチメントに適しています。欠点は、設定してアップグレードするインスタンスが多いことです。

ゲートウェイ。 1 つ以上の Collector が、アプリケーションやエージェントが送信する中央のサービスとして動作します。ゲートウェイは、重い処理やグローバルな処理を行う場所です。tail サンプリング、複数のバックエンドへのルーティング、レート制限、バックエンドの認証情報の保持です。ロードバランサーの背後で水平にスケールできるサービスです。

エージェントとゲートウェイ。 一般的な本番の設計：エージェントはローカルでの収集と軽いエンリッチメントを行い、OTLP でゲートウェイに転送し、ゲートウェイが中央の処理を行って、バックエンドにエクスポートします。アプリケーションの設定を単純に保ち（ノードのエージェントに送信）、バックエンドの認証情報を 1 か所に保ち、各層に 1 つの仕事を与えます。

App ─OTLP─▶ エージェント（ノードごと）─OTLP─▶ ゲートウェイ（Deployment）─▶ バックエンド
                │ ホストのメトリクス、ログ、       │ tail サンプリング、ルーティング、
                │ k8s のメタデータ                │ 認証情報、リトライ

エージェントの設定

エージェントは、処理を最小限に保ち、すべてをゲートウェイに転送します。

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
      memory:
      filesystem:
      network:

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 75
    spike_limit_percentage: 15
  k8s_attributes:
    passthrough: true     # Pod の IP だけを記録し、残りはゲートウェイが調べる
  batch:

exporters:
  otlp/gateway:
    endpoint: otel-gateway.observability.svc.cluster.local:4317
    tls:
      insecure: true      # 本番では、層の間に本物の TLS を使う
    sending_queue:
      enabled: true
      queue_size: 2000
    retry_on_failure:
      enabled: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, k8s_attributes, batch]
      exporters: [otlp/gateway]
    metrics:
      receivers: [otlp, hostmetrics]
      processors: [memory_limiter, k8s_attributes, batch]
      exporters: [otlp/gateway]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, k8s_attributes, batch]
      exporters: [otlp/gateway]

passthrough: true は、2 層の設計の鍵です。エージェントは、Kubernetes の API を呼び出さずに、各 resource に Pod の IP を追加するだけです。ゲートウェイは、エージェントから到着したテレメトリがどこで生成されたかを見ることができないため、その IP を使ってエンリッチします。

ゲートウェイの設定

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

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 80
    spike_limit_percentage: 20
  k8s_attributes:
    auth_type: serviceAccount
    passthrough: false
    extract:
      metadata:
        - k8s.namespace.name
        - k8s.pod.name
        - k8s.deployment.name
        - k8s.node.name
    pod_association:
      - sources:
          - from: resource_attribute
            name: k8s.pod.ip
      - sources:
          - from: connection
  batch:

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true
  otlphttp/prometheus:
    endpoint: http://prometheus:9090/api/v1/otlp
  otlphttp/loki:
    endpoint: http://loki:3100/otlp

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, k8s_attributes, batch]
      exporters: [otlp/tempo]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, k8s_attributes, batch]
      exporters: [otlphttp/prometheus]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, k8s_attributes, batch]
      exporters: [otlphttp/loki]

ゲートウェイは、エージェントが付けた Pod の IP を読み取り、Kubernetes の API にその Pod のメタデータを尋ね、namespace、Pod、Deployment の名前を追加します。バックエンドのエンドポイントは製品によって異なるため、お使いのバージョンのバックエンドのドキュメントで、正確な OTLP のパスを確認してください（このライブラリの Grafana のガイドが、Grafana のスタックを説明しています）。

k8s_attributes のための Kubernetes の権限

この processor は Pod のメタデータを読み取るため、その service account には読み取りのアクセスが必要です。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: otel-k8s-attributes
rules:
  - apiGroups: [""]
    resources: ["pods", "namespaces", "nodes"]
    verbs: ["get", "watch", "list"]
  - apiGroups: ["apps"]
    resources: ["replicasets", "deployments", "statefulsets", "daemonsets"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["batch"]
    resources: ["jobs", "cronjobs"]
    verbs: ["get", "list", "watch"]

それを、processor を実行する service account にバインドします。Helm チャートの kubernetesAttributes の preset が、必要な RBAC を作成してくれます。エージェントが DaemonSet として動作し、引き渡しではなく自分で検索を行う場合は、filter.node_from_env_var に、（downward API からの）ノード名を運ぶ変数を設定します。そうすれば、各エージェントは自分のノードの Pod だけを監視し、大規模なクラスターでの API の負荷を低く保てます。

パターンの選択

状況	使うもの
プロトタイプ、1 つか 2 つのサービス	Collector なし、または 1 つのゲートウェイ
ノードのメトリクスやログファイルが必要	DaemonSet としてのエージェント
複数のチーム、中央のポリシー、tail サンプリング、バックエンドの認証情報を 1 か所に	エージェントとゲートウェイ
チームごとの厳格な分離	チームごとのゲートウェイ。必要に応じて、その背後に共有のプラットフォームのゲートウェイ

運用上の注意

• Service の背後で、少なくとも 2 つのゲートウェイのレプリカを実行し、ゲートウェイの再起動でデータが失われないように、エージェントにキューとリトライを持たせます。
• 信頼されたネットワークの外では、エージェントとゲートウェイの間に TLS を使い、ゲートウェイが公開されている場所では、送信者を認証します。
• 可能であれば、すべての層で同じ Collector のバージョンに固定し、ゲートウェイを最初にアップグレードします。
• tail サンプリングを追加する場合は、サンプリングのガイドのロードバランシングの層を、エージェントとサンプラーの間に追加します。