KubernetesにおけるOpenTelemetryCollector:スケーラブルなアーキテクチャ、サンプリング、ClickHouseへのエクスポート

このガイドでは、Kubernetes環境におけるOpenTelemetry Collectorのアーキテクチャ上の考慮事項、設定、デプロイ戦略について詳しく説明します。特に、スケーラビリティ、高度なサンプリング、およびClickHouseへの直接エクスポートに焦点を当てています。目的は、データ損失ゼロを保証する堅牢な本番環境対応の可観測性パイプラインを提供することです。

1. KubernetesにおけるOpenTelemetry Collectorのアーキテクチャ

KubernetesにOpenTelemetry Collectorをデプロイするには、明確なアーキテクチャ戦略が必要です。主なモデルは、エージェント（DaemonSet）、ゲートウェイ（Deployment）、またはハイブリッドアプローチです。各モデルは、リソース利用率、レイテンシ、処理能力の点で明確なトレードオフを伴います。

1.1 エージェント（DaemonSet）アーキテクチャ

エージェントアーキテクチャは、すべてのKubernetesノードにOpenTelemetry Collectorインスタンスをデプロイします。これは通常、DaemonSetを使用して実現され、各ノードでコレクターポッドが実行されるようにします。エージェントは主に、ローカルデータの収集と初期処理を担当します。

特徴:

• デプロイモデル: Kubernetes DaemonSet。
• データ収集: 同じノードで実行されているアプリケーションから、ホストレベルのスクレイピングまたはサイドカーとして直接テレメトリデータを収集します。
• 処理: 軽量なノードローカル処理（例：リソース属性のエンリッチメント、基本的なフィルタリング、ヘッドベースのサンプリング）を実行します。
• エクスポート: 通常、データを集中型ゲートウェイコレクターに転送するか、直接バックエンドに転送します。

利点:

• 低レイテンシ: アプリケーションからコレクターへのデータパスが最小限です。
• 回復力: ノードレベルの分離。1つのエージェントの障害が他のノードに影響を与えません。
• リソース分離: リソースがノード全体に分散され、単一の競合ポイントを防ぎます。
• ネットワーク効率: 初期収集のためのノード間ネットワークトラフィックを削減します。

欠点:

• リソースオーバーヘッド: 各ノードでコレクターインスタンスのオーバーヘッドが発生します。
• 限定的なグローバルコンテキスト: テールベースのサンプリングなど、グローバルな視点が必要な高度な処理には非効率です。
• 管理の複雑さ: 設定変更には、すべてのノードでのローリングアップデートが必要です。

ユースケース:

• ホストメトリクスとログの収集。
• ヘッドベースのサンプリングによるアプリケーショントレースの収集。
• 初期データエンリッチメント（例：Kubernetesメタデータの追加）。

例: OpenTelemetry Collector Agent DaemonSet

この例は、OTLPとPrometheusメトリクスを受信し、それらを転送するように構成されたOTel Collector Agentの基本的なDaemonSetを示しています。

apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
  name: otel-agent
  namespace: observability
spec:
  mode: daemonset
  image: otel/opentelemetry-collector-contrib:0.90.1
  hostNetwork: true # Required for host-level scraping
  serviceAccount: otel-collector
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
  config: |
    receivers:
      otlp:
        protocols:
          grpc:
          http:
      prometheus:
        config:
          scrape_configs:
            - job_name: 'kubernetes-nodes'
              static_configs:
                - targets: ['localhost:9100'] # Node Exporter
            - job_name: 'kubernetes-pods'
              kubernetes_sd_configs:
                - role: pod
              relabel_configs:
                - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
                  action: keep
                  regex: true
                - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
                  action: replace
                  target_label: __metrics_path__
                  regex: (.+)
                - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
                  action: replace
                  regex: ([^:]+)(?::\d+)?;(\d+)
                  replacement: $1:$2
                  target_label: __address__
    processors:
      batch:
        send_batch_size: 10000
        timeout: 10s
      memory_limiter:
        limit_mib: 150
        spike_limit_mib: 50
        check_interval: 1s
      resourcedetection:
        detectors: [env, system, kubernetes]
        timeout: 2s
        override: true
    exporters:
      otlp:
        endpoint: "otel-gateway.observability.svc.cluster.local:4317" # Forward to Gateway
        tls:
          insecure: true
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [resourcedetection, batch, memory_limiter]
          exporters: [otlp]
        metrics:
          receivers: [otlp, prometheus]
          processors: [resourcedetection, batch, memory_limiter]
          exporters: [otlp]

1.2 ゲートウェイ（Deployment）アーキテクチャ

ゲートウェイアーキテクチャは、集中型のOpenTelemetry Collectorデプロイメントを採用しており、通常はKubernetes Deploymentとして水平にスケーリングされます。これらのコレクターは、エージェントまたはアプリケーションから直接データを受信し、高度な処理を実行して、さまざまなバックエンドにエクスポートします。

特徴:

• デプロイモデル: Kubernetes Deployment。多くの場合、Serviceを介して公開されます。
• データ収集: エージェントまたはアプリケーションから直接集約されたデータを受信します。
• 処理: 複雑でリソースを大量に消費する操作（例：テールベースのサンプリング、属性操作、集約、ファンアウト）を実行します。
• エクスポート: 処理されたデータを長期ストレージまたは分析プラットフォーム（例：ClickHouse、Prometheus、Jaeger、Loki）にエクスポートします。

利点:

• 集中処理: テールベースのサンプリングなど、グローバルな視点が必要な操作に最適です。
• リソース効率: 複数のデータストリーム間でリソースを共有するため、複雑な処理の場合、ノードごとのエージェントと比較して全体的なリソースフットプリントを削減できる可能性があります。
• 管理の簡素化: コア処理ロジックのために管理するインスタンスが少なくなります。
• スケーラビリティ: レプリカ数を増やすことで簡単に水平スケーリングできます。

欠点:

• レイテンシの増加: データはネットワークを2回通過する必要があります（アプリケーション -> エージェント -> ゲートウェイ -> バックエンド）。
• 単一障害点（スケーリングされていない場合）: 単一のゲートウェイインスタンスの障害は、パイプライン全体を中断させる可能性があります。
• ネットワークオーバーヘッド: すべてのテレメトリデータがゲートウェイを通過するため、ネットワークリンクが飽和する可能性があります。

ユースケース:

• トレースのテールベースのサンプリング。
• 複数のソースからのメトリクスの集約。
• 複雑なデータ変換とフィルタリング。
• 複数のバックエンドシステムへのエクスポート。

例: OpenTelemetry Collector Gateway Deployment

この例は、OTLPを受信、処理、エクスポートするように構成されたOTel Collector GatewayのDeploymentを示しています。

apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
  name: otel-gateway
  namespace: observability
spec:
  mode: deployment
  image: otel/opentelemetry-collector-contrib:0.90.1
  replicas: 3 # Scaled for high availability and throughput
  serviceAccount: otel-collector
  ports:
    - name: otlp-grpc
      port: 4317
      targetPort: 4317
      protocol: TCP
    - name: otlp-http
      port: 4318
      targetPort: 4318
      protocol: TCP
    - name: metrics
      port: 8888
      targetPort: 8888
      protocol: TCP
  resources:
    requests:
      memory: "1Gi"
      cpu: "500m"
    limits:
      memory: "2Gi"
      cpu: "1000m"
  config: |
    receivers:
      otlp:
        protocols:
          grpc:
          http:
    processors:
      batch:
        send_batch_size: 10000
        timeout: 10s
      memory_limiter:
        limit_mib: 1500
        spike_limit_mib: 500
        check_interval: 1s
      # Tail sampling configuration will be added here later
    exporters:
      # ClickHouse exporter will be added here later
      logging:
        verbosity: detailed
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, memory_limiter] # Tail sampling will be inserted here
          exporters: [logging] # ClickHouse exporter will replace/augment this
        metrics:
          receivers: [otlp]
          processors: [batch, memory_limiter]
          exporters: [logging] # ClickHouse exporter will replace/augment this

1.3 ハイブリッドアーキテクチャ（推奨）

ハイブリッドアーキテクチャは、エージェントモデルとゲートウェイモデルの両方の長所を兼ね備えています。エージェントはデータをローカルで収集し、ゲートウェイに転送します。ゲートウェイは高度な処理とエクスポートを実行します。これは、ほとんどの本番環境で推奨されるアプローチです。

特徴:

• エージェント（DaemonSet）: データを収集し、最小限の処理（例：リソースエンリッチメント）を実行し、ゲートウェイに転送します。
• ゲートウェイ（Deployment）: エージェントからデータを受信し、高度な処理（例：テールベースのサンプリング、集約）を実行し、バックエンドにエクスポートします。

利点:

• 最適なパフォーマンス: 初期収集のレイテンシが低く、集中型で強力な処理が可能です。
• 高可用性: エージェントはローカルの回復力を提供し、ゲートウェイは高可用性のためにスケーリングできます。
• スケーラビリティ: 両方のレイヤーを独立してスケーリングできます。
• 柔軟性: 各ステージで異なる処理ロジックを可能にします。

欠点:

• 複雑さの増加: 2つの異なるコレクターデプロイメントとその相互作用を管理する必要があります。
• 高いリソースフットプリント: ノードごとのエージェントがあるため、純粋なゲートウェイモデルよりも全体的なリソース消費量が高くなります。

例: エージェントからゲートウェイへの転送（エージェント設定スニペット）

セクション1.1のエージェント設定は、ゲートウェイへの転送をすでに示しています。

    exporters:
      otlp:
        endpoint: "otel-gateway.observability.svc.cluster.local:4317" # Forward to Gateway
        tls:
          insecure: true

1.4 アーキテクチャ比較表

2. OpenTelemetry Collector設定の基本

OpenTelemetry Collectorを効果的に運用するには、適切に構造化された設定が不可欠です。このセクションでは、本番デプロイメントに不可欠な基本的なプロセッサーとエクスポーターについて説明します。

2.1 コアコンポーネント: レシーバー、プロセッサー、エクスポーター、サービス

OpenTelemetry Collectorの設定は宣言的であり、次の4つの主要コンポーネントを中心に構成されています。

• レシーバー（Receivers）: データがコレクターにどのように取り込まれるか（例：OTLP、Prometheus、Jaeger、Zipkin）。
• プロセッサー（Processors）: コレクター内でデータがどのように変換、フィルタリング、またはエンリッチされるか（例：batch、memory_limiter、tail_sampling、resourcedetection）。
• エクスポーター（Exporters）: データがコレクターからさまざまなバックエンドにどのように送られるか（例：OTLP、ClickHouse、Prometheus、Loki、Jaeger）。
• サービス（Service）: 特定のテレメトリタイプ（トレース、メトリクス、ログ）について、レシーバーをプロセッサーに、そしてエクスポーターに接続するパイプラインを定義します。

2.2 効率のためのバッチ処理

batchプロセッサーは、ネットワーク利用率を最適化し、バックエンドシステムの負荷を軽減するために不可欠です。これは、エクスポートする前にテレメトリデータをより大きなバッチに集約します。

利点:

• ネットワーク呼び出しの削減: 多くの小さなリクエストではなく、より少ない大きなリクエストになります。
• スループットの向上: バックエンドは、より大きなデータチャンクをより効率的に処理できます。
• CPU使用率の低下: シリアライズとネットワークI/Oの項目あたりのオーバーヘッドが少なくなります。

設定パラメータ:

• send_batch_size: 単一のバッチで送信するテレメトリ項目（スパン、メトリックデータポイント、ログレコード）の最大数。
• timeout: send_batch_sizeに達していなくても、バッチを送信するまでに待機する最大期間。
• send_batch_max_size: 過度に大きなバッチを防ぐために、必要に応じてsend_batch_sizeを上書きするバッチの絶対最大サイズ。

例: batchプロセッサー設定

    processors:
      batch:
        send_batch_size: 10000 # Max items per batch
        timeout: 10s         # Max wait time before sending
        send_batch_max_size: 12000 # Absolute max items, useful for high-volume bursts

2.3 安定性のためのメモリリミッター

memory_limiterプロセッサーは、OpenTelemetry Collectorが過剰なメモリを消費し、KubernetesによってOOMKilledされるのを防ぐために不可欠です。メモリ使用量を監視し、制限に近づくと、クラッシュを防ぐためにデータをドロップします。

利点:

• OOMKillsの防止: 高負荷時や設定ミス時でもコレクターの安定性を確保します。
• 段階的な劣化: メモリ負荷時に、データ完全性よりもコレクターの稼働時間を優先します。

設定パラメータ:

• limit_mib: コレクターが使用できる最大メモリ量（MiB）。この制限に達すると、データはドロップされます。これは、コンテナのKubernetesメモリ制限よりも小さくする必要があります。
• spike_limit_mib: コレクターが一時的にlimit_mibを超えることができる最大メモリ量（MiB）。これにより、突然のスパイクを即座のデータドロップなしで処理できます。
• check_interval: メモリ使用量をチェックする頻度（期間）。

例: memory_limiterプロセッサー設定

    processors:
      memory_limiter:
        limit_mib: 1500 # Max memory in MiB before dropping data
        spike_limit_mib: 500 # Allowed spike above limit_mib
        check_interval: 1s # How often to check memory usage

注: limit_mibは、KubernetesがOOMKilledする前にコレクターが反応できるように、常にKubernetesコンテナのlimits.memoryよりも低く設定する必要があります。経験則として、limit_mib = limits.memory * 0.75です。

2.4 ゲートウェイへのトレースのロードバランシング

ハイブリッドアーキテクチャを使用する場合、エージェントは高可用性と負荷分散のために、複数のゲートウェイインスタンスにトレースを分散する必要があります。loadbalancingエクスポーターはこれを容易にします。

利点:

• 高可用性: 1つのゲートウェイが故障した場合、エージェントは自動的に健全なゲートウェイにルーティングします。
• 負荷分散: 複数のゲートウェイインスタンスにトレースの取り込みを分散します。
• スケーラビリティ: エージェントを再設定することなく、ゲートウェイの水平スケーリングを可能にします。

設定パラメータ:

• protocol: 使用するOTLPプロトコル（grpcまたはhttp）。
• resolver: ターゲットエンドポイントの検出方法を定義します。
  • dns: DNS SRVレコードまたはAレコードを使用してエンドポイントを検出します。Kubernetesサービスに推奨されます。
  • static: 固定されたエンドポイントのリスト。動的ではありません。
• routing_key: トレースのルーティング方法を決定します。traceIDはデフォルトであり、単一トレースのすべてのスパンが適切な処理（例：テールサンプリング）のために同じゲートウェイに送られるようにするために推奨されます。

例: エージェントloadbalancingエクスポーター設定

    exporters:
      otlp/loadbalancer:
        endpoint: "otel-gateway.observability.svc.cluster.local:4317" # Kubernetes Service DNS
        tls:
          insecure: true
        loadbalancing:
          resolver:
            dns:
              hostname: otel-gateway.observability.svc.cluster.local # Service DNS name
              port: 4317
          routing_key: traceID # Ensures all spans of a trace go to the same gateway
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [resourcedetection, batch, memory_limiter]
          exporters: [otlp/loadbalancer] # Use the loadbalancing exporter

3. 高度なサンプリング戦略: テールベースのサンプリング

サンプリングは、テレメトリデータ、特にトレースの量を管理するために非常に重要です。ヘッドベースのサンプリング（トレースの開始時に決定する）は単純ですが、貴重なコンテキストを破棄することがよくあります。テールベースのサンプリングは、トレースが完了した後にサンプリングの決定を行うことで、この問題に対処します。

3.1 なぜテールベースのサンプリングなのか？

テールベースのサンプリングにより、トレース全体のコンテキストに基づいてインテリジェントなサンプリング決定を行うことができます。これにより、確実に次のものをキャプチャできます。

• エラーのあるトレース: エラーを含むすべてのトレース。
• 遅いトレース: 特定のレイテンシしきい値を超えるすべてのトレース。
• 特定の操作: 重要なビジネス操作を含むトレース。

利点:

• コンテキストの完全性: 分析のために完全なトレースがキャプチャされることを保証します。
• ターゲットを絞ったデータ収集: トラブルシューティングに最も関連性の高いトレースに焦点を当てます。

トレードオフ:

• 集中処理: トレースが完了するまでメモリに保持するためにゲートウェイコレクターが必要となり、ゲートウェイのメモリとCPU要件が増加します。
• レイテンシの増加: トレースが完了するまで決定が遅延するため、トレースがエクスポートされるまでにわずかな遅延が追加される可能性があります。

3.2 tail_samplingプロセッサー設定

tail_samplingプロセッサーはゲートウェイコレクター内で設定されます。これは、サンプリングポリシーを適用する前に、指定された期間（decision_wait）トレースを保持してすべてのスパンを収集します。

主要パラメータ:

• decision_wait: サンプリング決定を行う前に、トレースのすべてのスパンが到着するのを待機する最大期間。これはトレースの完全性を確保するために非常に重要です。
• num_traces: メモリに同時に保持するトレースの最大数。これはメモリ使用量に直接影響します。
• expected_new_traces_per_sec: 内部サイジングに使用される、受信トレースレートの推定値。

ポリシータイプ: tail_samplingプロセッサーはさまざまなポリシーをサポートしており、andまたはor複合ポリシーを使用して組み合わせることができます。

• always_sample: 常にトレースをサンプリングします。
• drop_new: num_tracesを超えた場合、新しいトレースをドロップします。
• probabilistic: 設定された確率に基づいてトレースをサンプリングします。
• rate_limiting: 1秒あたりの最大レートでトレースをサンプリングします。
• status_code: HTTPステータスコードに基づいてトレースをサンプリングします（例：ERROR、UNSET）。
• latency: 指定されたレイテンシしきい値を超えるトレースをサンプリングします。
• attribute: 特定のスパンまたはリソース属性に基づいてトレースをサンプリングします。
• composite: andまたはorロジックを使用して複数のポリシーを組み合わせます。

例: tail_samplingポリシーを持つcompositeプロセッサー

この設定は、エラーを含む、またはレイテンシが500msを超えるすべてのトレースをサンプリングします。

    processors:
      # ... other processors like batch, memory_limiter
      tail_sampling:
        decision_wait: 10s # Wait up to 10 seconds for all spans of a trace
        num_traces: 100000 # Max traces to hold in memory
        expected_new_traces_per_sec: 1000 # Expected incoming rate
        policies:
          - name: error-or-slow-trace
            type: composite
            composite:
              or_policies:
                - name: error-policy
                  type: status_code
                  status_code:
                    status_codes: [ERROR]
                - name: slow-trace-policy
                  type: latency
                  latency:
                    threshold_ms: 500 # Sample traces > 500ms
              on_failure: always_sample # If composite policy fails, always sample

ゲートウェイパイプラインへの統合:

    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, memory_limiter, tail_sampling] # Insert tail_sampling here
          exporters: [logging] # Exporters will follow

4. データ損失ゼロでClickHouseにエクスポート

ClickHouseは、高スループットの取り込みと高速クエリ実行に最適化された分析データベースであり、OpenTelemetryのトレースとメトリクスを保存するのに優れた選択肢です。clickhouseエクスポーターは直接統合を可能にします。

4.1 ClickHouseエクスポーターの概要

clickhouseエクスポーターは、トレース、メトリクス、ログをClickHouseテーブルに直接送信します。テーブルスキーマ、TTL、圧縮に関するさまざまな設定をサポートしています。

4.2 トレースの設定

トレースは通常、trace_id、service_name、operation_name、および時間範囲で効率的にクエリできるように設計されたテーブルに保存されます。

ClickHouseトレースのスキーマに関する考慮事項: ClickHouseにおけるOpenTelemetryトレースの一般的なスキーマには以下が含まれます。

• trace_id (FixedString(16))
• span_id (FixedString(8))
• parent_span_id (FixedString(8))
• service_name (String)
• operation_name (String)
• start_time_unix_nano (UInt64)
• duration_nano (Int64)
• kind (Int8)
• status_code (Int8)
• status_message (String)
• attributes (Map(String, String)) - スパン属性用
• resource_attributes (Map(String, String)) - リソース属性用
• events.timestamp_unix_nano (Array(UInt64))
• events.name (Array(String))
• events.attributes (Array(Map(String, String)))
• links.trace_id (Array(FixedString(16)))
• links.span_id (Array(FixedString(8)))
• links.attributes (Array(Map(String, String)))

例: トレースのClickHouseエクスポーター設定

    exporters:
      clickhouse/traces:
        dsn: "tcp://clickhouse-cluster.observability.svc.cluster.local:9000?database=otel"
        database: otel
        traces_table: otel_traces
        ttl: 7d # Data retention for 7 days
        compression: lz4 # Use LZ4 compression
        # Optional: Define specific schema mappings if default is not sufficient
        # trace_id_field: trace_id
        # span_id_field: span_id
        # ...

otel_tracesテーブルのClickHouse DDL:

CREATE TABLE otel_traces (
    Timestamp DateTime64(9) CODEC(Delta, ZSTD(1)),
    TraceId FixedString(16) CODEC(ZSTD(1)),
    SpanId FixedString(8) CODEC(ZSTD(1)),
    ParentSpanId FixedString(8) CODEC(ZSTD(1)),
    TraceState String CODEC(ZSTD(1)),
    SpanName String CODEC(ZSTD(1)),
    SpanKind Int8 CODEC(ZSTD(1)),
    ServiceName LowCardinality(String) CODEC(ZSTD(1)),
    ResourceSchemaUrl String CODEC(ZSTD(1)),
    ResourceAttributes Map(LowCardinality(String), String) CODEC(ZSTD(1)),
    ScopeSchemaUrl String CODEC(ZSTD(1)),
    ScopeName String CODEC(ZSTD(1)),
    ScopeVersion String CODEC(ZSTD(1)),
    SpanAttributes Map(LowCardinality(String), String) CODEC(ZSTD(1)),
    DurationNanos UInt64 CODEC(ZSTD(1)),
    StatusCode Int8 CODEC(ZSTD(1)),
    StatusMessage String CODEC(ZSTD(1)),
    Events Nested (
        Timestamp DateTime64(9),
        Name String,
        Attributes Map(LowCardinality(String), String)
    ) CODEC(ZSTD(1)),
    Links Nested (
        TraceId FixedString(16),
        SpanId FixedString(8),
        TraceState String,
        Attributes Map(LowCardinality(String), String)
    ) CODEC(ZSTD(1))
) ENGINE = MergeTree()
PARTITION BY toYYYYMMDD(Timestamp)
ORDER BY (ServiceName, SpanName, Timestamp, TraceId)
TTL Timestamp + INTERVAL 7 DAY
SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1;

4.3 メトリクスの設定

メトリクスは通常、時系列に最適化されたテーブルに保存されます。