メインコンテンツへスキップ
OTel FYI をお試しください。OTel collector のドキュメントをわかりやすく簡潔にまとめていますOTel FYI では、receiver、プロセッサ、エクスポーター、パイプラインを網羅した、明快で簡潔な OpenTelemetry collector のドキュメントを提供しています。ClickStack OTel collector の設定時に役立つ補助リソースです。
このページでは、公式の ClickStack OpenTelemetry (OTel) collector の設定方法について詳しく説明します。

​
collector の役割

OpenTelemetry collector は、主に次の 2 つの役割でデプロイできます。
  • エージェント - エージェント インスタンスは、サーバーや Kubernetes ノード上などのエッジでデータを収集するほか、OpenTelemetry SDK でインストルメントされたアプリケーションからイベントを直接受信することもできます。後者の場合、エージェント インスタンスはアプリケーションとともに、またはアプリケーションと同じホスト上で (サイドカーやデーモンセットなどとして) 実行されます。エージェントは、データを ClickHouse に直接送信することも、ゲートウェイ インスタンスに送信することもできます。前者は Agent deployment pattern と呼ばれます。
  • ゲートウェイ - ゲートウェイ インスタンスは、独立したサービス (たとえば Kubernetes 上のデプロイメント) として提供され、通常はクラスターごと、データセンターごと、またはリージョンごとに配置されます。これらは、単一の OTLP エンドポイントを介して、アプリケーション (またはエージェントとして動作する他の collector) からイベントを受信します。通常は複数のゲートウェイ インスタンスをデプロイし、それらの間で負荷を分散するために標準のロードバランサーを使用します。すべてのエージェントとアプリケーションがこの単一のエンドポイントにシグナルを送信する場合、これは Gateway deployment pattern と呼ばれることがよくあります。
重要: ClickStack のデフォルト ディストリビューションに含まれるものも含め、collector は 以下で説明するゲートウェイの役割 を前提としており、エージェントまたは SDK からデータを受信します。 エージェントの役割で OTel collector をデプロイするユーザーは、通常、ClickStack 版ではなく collector のデフォルトの contrib ディストリビューション を使用しますが、Fluentd や Vector などの他の OTLP 互換技術を使用することもできます。

​
collectorのデプロイ


Managed ClickStack へ送信する際は、可能であればゲートウェイロールに collector の公式 ClickStack ディストリビューションの使用を推奨します。独自の collector を使用する場合は、ClickHouse エクスポーターが含まれていることを確認してください。collector は、Helm (Kubernetes 環境での使用を推奨) または Docker を使用してデプロイできます。公式の ClickStack Helm チャート は、ClickStack のディストリビューションイメージをあらかじめ設定した状態で、上流の OpenTelemetry Collector Helm チャート をサブチャートとして組み込んでいます。HyperDX を含むフルスタック全体をインストールする場合は、ClickStack Helm デプロイメントガイド を参照してください。standalone の collector デプロイメントの場合は、以下に示すように、上流のチャートを ClickStack イメージと直接組み合わせて使用できます。
OpenTelemetry のアップストリーム Helm リポジトリを追加します。
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
ClickStack イメージと Managed ClickStack の認証情報を設定する values.yaml を作成します。
# values.yaml
mode: deployment

image:
  repository: docker.clickhouse.com/clickhouse/clickstack-otel-collector
  tag: "2.19.0"

ports:
  otlp:
    enabled: true
  otlp-http:
    enabled: true

extraEnvs:
  - name: CLICKHOUSE_ENDPOINT
    value: "https://your-instance.clickhouse.cloud:8443"
  - name: CLICKHOUSE_USER
    value: "default"
  - name: CLICKHOUSE_PASSWORD
    value: "<password>"
チャートをインストールします。
helm install clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml
本番環境へのデプロイでは、CLICKHOUSE_PASSWORD の値を直接埋め込むのではなく、Kubernetes Secret に保存して extraEnvsFrom 経由で参照することを推奨します。
対象の ClickHouse インスタンスは、環境変数 CLICKHOUSE_ENDPOINT、CLICKHOUSE_USERNAME、CLICKHOUSE_PASSWORD を使用して設定します。CLICKHOUSE_ENDPOINT には、プロトコルとポートを含む完全な ClickHouse Cloud HTTP エンドポイントを指定してください (例: https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443) 。Managed ClickStack の認証情報の取得方法については、こちらを参照してください。
本番環境用ユーザー本番環境では、適切な認証情報を持つユーザーを使用してください。

​
設定の変更

​
Managed ClickStack インスタンスの設定

OpenTelemetry collectorは、環境変数 CLICKHOUSE_ENDPOINT、CLICKHOUSE_USERNAME、CLICKHOUSE_PASSWORD を通じて、Managed ClickStack インスタンスを使用するよう設定できます。これらの設定方法は、デプロイメント方法によって異なります。
values.yaml の extraEnvs で該当するエントリを上書きしてから、リリースをアップグレードします。
# values.yaml
extraEnvs:
  - name: CLICKHOUSE_ENDPOINT
    value: "<HTTPS_ENDPOINT>"
  - name: CLICKHOUSE_USER
    value: "<CLICKHOUSE_USER>"
  - name: CLICKHOUSE_PASSWORD
    value: "<CLICKHOUSE_PASSWORD>"

helm upgrade clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml

​
collector の設定を拡張する

ClickStack 版の OTel collector では、カスタム設定ファイルをマウントし、環境変数を設定することで、ベース設定を拡張できます。カスタムの receiver、プロセッサ、またはパイプラインを追加するには、次の手順に従います。
  1. 追加設定を含むカスタム設定ファイルを作成します
  2. ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントします
  3. 環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定します
カスタム設定の例:
receivers:
  # ローカルファイルからログを収集する
  filelog:
    include:
      - /var/log/**/*.log
      - /var/log/syslog
      - /var/log/messages
    start_at: beginning

  # ホストシステムのメトリクスを収集する
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
        metrics:
          system.cpu.utilization:
            enabled: true
      memory:
        metrics:
          system.memory.utilization:
            enabled: true
      disk:
      network:
      filesystem:
        metrics:
          system.filesystem.utilization:
            enabled: true

service:
  pipelines:
    # ログパイプライン
    logs/host:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
    
    # メトリクスパイプライン
    metrics/hostmetrics:
      receivers: [hostmetrics]
      processors:
        - memory_limiter
        - batch
      exporters:
        - clickhouse
スタンドアロン collector を使用してデプロイする:
docker run -d \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  # -e OPAMP_SERVER_URL=${OPAMP_SERVER_URL} \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -v "$(pwd)/custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-otel-collector:latest
カスタム設定では、新しい receiver、プロセッサ、パイプラインのみを定義します。ベースのプロセッサ (memory_limiter、batch) と exporter (clickhouse) はすでに定義されているため、名前を指定して参照してください。カスタム設定はベース設定にマージされるため、既存のコンポーネントを上書きすることはできません。
より複雑な設定については、デフォルトの ClickStack collector 設定およびClickHouse exporter のドキュメントを参照してください。

​
設定構造

receivers、operators、processors など、OTel collector の設定方法の詳細については、OpenTelemetry collector の公式ドキュメントを参照することを推奨します。

​
Docker Compose

Docker Composeを使用する場合は、上記と同じ環境変数を使用してcollectorのconfigurationを変更します。
otel-collector:
    image: hyperdx/hyperdx-otel-collector
    environment:
      CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443'
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      CLICKHOUSE_USER: 'default'
      CLICKHOUSE_PASSWORD: 'password'
      CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml'
    ports:
      - '13133:13133' # health_check 拡張機能
      - '24225:24225' # Fluentd receiver
      - '4317:4317' # OTLP gRPC receiver
      - '4318:4318' # OTLP HTTP receiver
      - '8888:8888' # メトリクス拡張機能
    volumes:
      - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
    restart: always
    networks:
      - internal

​
collector の保護

デフォルトでは、ClickStack OpenTelemetry collector は、オープンソース版以外でデプロイした場合は保護されておらず、OTLP ポートでの認証も不要です。インジェストを保護するには、collector のデプロイ時に OTLP_AUTH_TOKEN 環境変数で認証トークンを指定します。設定方法はデプロイ方法によって異なります。
values.yaml の extraEnvs に OTLP_AUTH_TOKEN を追加し、その後リリースをアップグレードします。
# values.yaml
extraEnvs:
  - name: OTLP_AUTH_TOKEN
    value: "a_very_secure_string"
  - name: CLICKHOUSE_ENDPOINT
    value: "<HTTPS_ENDPOINT>"
  - name: CLICKHOUSE_USER
    value: "<CLICKHOUSE_USER>"
  - name: CLICKHOUSE_PASSWORD
    value: "<CLICKHOUSE_PASSWORD>"

helm upgrade clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml
本番環境では、OTLP_AUTH_TOKEN と CLICKHOUSE_PASSWORD を Kubernetes Secret に保存し、extraEnvsFrom 経由で参照することを推奨します。
あわせて、以下も推奨します。
  • collector が ClickHouse と HTTPS 経由で通信するよう設定する。
  • 権限を限定した、インジェスト専用のユーザーを作成する。詳細は以下を参照してください。
  • SDK/agent と collector 間の通信を暗号化するため、OTLP エンドポイントで TLS を有効にする。これは custom collector configuration で設定できます。

​
インジェスト用ユーザーの作成

Managed ClickStack にインジェストするために、OTel collector 専用のデータベースとユーザーを作成することを推奨します。このユーザーには、ClickStack が作成して使用するテーブル を作成し、それらに insert できる権限を付与してください。
CREATE DATABASE otel;
CREATE USER hyperdx_ingest IDENTIFIED WITH sha256_password BY 'ClickH0u3eRocks123!';
GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON otel.* TO hyperdx_ingest;
これは、collector がデータベース otel を使用するように設定されていることを前提としています。これは環境変数 HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE で制御できます。ほかの環境変数と同様に、これを collector に渡してください。

​
処理 - フィルタリング、変換、エンリッチ

ユーザーは、インジェスト時にイベントメッセージのフィルタリング、変換、エンリッチを行いたくなるのが一般的です。ClickStack コネクタの構成は変更できないため、追加のイベントフィルタリングや処理が必要な場合は、次のいずれかを推奨します。
  • フィルタリングや処理を行う独自の OTel collector をデプロイし、イベントを OTLP 経由で ClickStack collector に送信して ClickHouse に取り込む。
  • 独自の OTel collector をデプロイし、ClickHouse exporter を使用してイベントを ClickHouse に直接送信する。
OTel collector を使って処理を行う場合は、変換はゲートウェイインスタンスで実施し、エージェントインスタンスでの処理は最小限に抑えることを推奨します。これにより、サーバー上で動作するエッジ側エージェントに必要なリソースをできるだけ小さくできます。一般的に、ユーザーがエージェントで行うのは、フィルタリング (不要なネットワーク使用を最小限に抑えるため) 、timestamp の設定 (operator 経由) 、およびコンテキストを必要とするエンリッチのみです。たとえば、ゲートウェイインスタンスが別の Kubernetes クラスターにある場合、k8s のエンリッチはエージェントで行う必要があります。 OpenTelemetry は、活用できる次の処理およびフィルタリング機能をサポートしています。
  • プロセッサ - プロセッサは、receiver が収集したデータを変更または変換し、エクスポーターに送信する前に処理します。プロセッサは、collector 構成の processors セクションで設定された順序どおりに適用されます。これらは任意ですが、最小限のセットを使うことが通常は推奨されています。ClickHouse とともに OTel collector を使用する場合、プロセッサは次のものに限定することを推奨します。
  • memory_limiter は、collector でメモリ不足が発生するのを防ぐために使用します。推奨事項については、Estimating Resources を参照してください。
  • コンテキストに基づくエンリッチを行うプロセッサ。たとえば、Kubernetes Attributes Processor を使うと、spans、メトリクス、logs の resource attributes を k8s メタデータで自動的に設定できます。たとえば、イベントに送信元ポッドの id を付与できます。
  • traces に必要な場合の Tail or head sampling。
  • Basic filtering - operator 経由で実施できない場合に、不要なイベントを破棄します (以下を参照) 。
  • Batching - ClickHouse を扱う際には、データをバッチで送信するために不可欠です。「Optimizing inserts」 を参照してください。
  • 演算子 - Operators は、receiver で利用できる最も基本的な処理単位です。基本的なパースがサポートされており、Severity や Timestamp などのフィールドを設定できます。ここでは JSON や regex のパースに加えて、イベントのフィルタリングや基本的な変換もサポートされています。イベントのフィルタリングはここで行うことを推奨します。
演算子や transform processors を使って過度なイベント処理を行うのは避けることを推奨します。これらは、特に JSON パースで、かなりのメモリおよび CPU オーバーヘッドを招く可能性があります。いくつかの例外はあるものの、すべての処理は ClickHouse で insert time に materialized view とカラムを使って実行できます。例外となるのは、k8s メタデータの追加のようなコンテキストを認識したエンリッチです。詳細については、Extracting structure with SQL を参照してください。

​
例

次の設定は、この非構造化のログファイルを収集する方法を示しています。この設定は、エージェント ロールの collector が ClickStack ゲートウェイにデータを送信する際に使用できます。 ログ行から構造を抽出する演算子 (regex_parser) やイベントをフィルタリングする演算子に加えて、イベントをバッチ化し、メモリ使用量を制限する プロセッサ を使用している点に注目してください。
file=code_snippets/ClickStack/config-unstructured-logs-with-processor.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-unstructured.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<ip>[\d.]+)\s+-\s+-\s+\[(?P<timestamp>[^\]]+)\]\s+"(?P<method>[A-Z]+)\s+(?P<url>[^\s]+)\s+HTTP/[^\s]+"\s+(?P<status>\d+)\s+(?P<size>\d+)\s+"(?P<referrer>[^"]*)"\s+"(?P<user_agent>[^"]*)"'
        timestamp:
          parse_from: attributes.timestamp
          layout: '%d/%b/%Y:%H:%M:%S %z'
          #22/Jan/2019:03:56:14 +0330
processors:
  batch:
    timeout: 1s
    send_batch_size: 10000
  memory_limiter:
    check_interval: 1s
    limit_mib: 2048
    spike_limit_mib: 256
exporters:
  # HTTPセットアップ
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_INGESTION_API_KEY>
    compression: gzip

  # gRPCセットアップ（代替）
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # 同一ホスト上で2つのcollectorが稼働するため変更
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]
OTLP 通信では、必ずインジェスト API key を含む authorization headerを付与する必要がある点に注意してください。 より高度な設定については、OpenTelemetry Collector のドキュメントを参照することをお勧めします。

​
挿入の最適化

高い insert パフォーマンスを実現しつつ、強い整合性保証を得るには、ClickStack collector 経由でオブザーバビリティデータを ClickHouse に挿入する際に、いくつかの基本的なルールに従う必要があります。OTel collector を適切に設定すれば、以下のルールは容易に実践できます。これにより、ClickHouse を初めて使うユーザーが直面しがちな一般的な問題も回避できます。

​
バッチ化

デフォルトでは、ClickHouse に送信される insert ごとに、ClickHouse はその insert のデータと、保存に必要なその他のメタデータを含むストレージ part を直ちに作成します。そのため、各 insert に含まれるデータ量が少ない多数の insert を送るよりも、各 insert により多くのデータを含めた少数の insert を送るほうが、必要な書き込み回数を減らせます。データは 1 回あたり少なくとも 1,000 行の、ある程度大きな batches で insert することを推奨します。詳細はこちらを参照してください。 デフォルトでは、ClickHouse への insert は同期的であり、内容が同一であればべき等です。merge tree engine family の table では、ClickHouse はデフォルトで自動的に insert を deduplicate します。つまり、たとえば次のようなケースでも insert は安全に再試行できます。
  • (1) データを受信するノードに問題がある場合、INSERT クエリは timeout するか、より具体的な error を返し、確認応答は返されません。
  • (2) ノードがデータを書き込めたとしても、ネットワークの中断によって確認応答をクエリの送信元に返せない場合、送信元は timeout またはネットワーク error を受け取ります。
collector の観点では、(1) と (2) を区別するのは難しいことがあります。ただし、どちらの場合でも、確認応答のない insert はすぐに再試行できます。再試行した INSERT クエリに同じデータが同じ順序で含まれている限り、元の (確認応答のない) insert が成功していれば、ClickHouse は再試行された insert を自動的に無視します。 このため、OTel collector の ClickStack distribution では batch プロセッサ を使用しています。これにより、上記の要件を満たす、一貫した batches of rows として insert が送信されます。collector に high throughput (1 秒あたりのイベント数) が見込まれ、かつ各 insert で少なくとも 10,000 件のイベントを送信できる場合、通常、pipeline で必要なバッチ化はこれだけです。メモリが許すなら、100,000 までの値を使用できます。この場合、collector は batch プロセッサ の timeout に達する前に batches を flush するため、pipeline 全体の end-to-end latency を低く保ちつつ、batches のサイズも一定に保てます。

​
非同期挿入を使用する

通常、collector のスループットが低い場合、ユーザーは小さなバッチを送らざるを得ない一方で、データはエンドツーエンドのレイテンシを最小限に抑えて ClickHouse に到達してほしいと考えます。この場合、batch processor の timeout に達すると小さなバッチが送信されます。これは問題の原因になることがあり、そのような場合に非同期挿入が必要になります。なお、ゲートウェイとして動作する ClickStack collector にデータを送信している場合、この問題が発生することはまれです。collector が集約ポイントとして機能し、この問題を緩和するためです。詳しくは collector の役割 を参照してください。 大きなバッチを確実に用意できない場合は、Asynchronous Inserts を使って、バッチ化を ClickHouse に委ねることができます。非同期挿入では、データはいったんバッファに挿入され、その後、データベースストレージに書き込まれます。 非同期挿入を有効化すると、ClickHouse ① が INSERT クエリを受信した時点で、クエリのデータはまず ② メモリ内バッファに即座に書き込まれます。③ 次回のバッファ flush が行われると、バッファ内のデータはソートされ、part としてデータベースストレージに書き込まれます。なお、データはデータベースストレージに flush されるまで、クエリから検索できません。バッファ flush は設定可能です。 collector で非同期挿入を有効にするには、接続文字列に async_insert=1 を追加します。配信保証を得るため、wait_for_async_insert=1 (既定値) を使用することを推奨します。詳細は こちら を参照してください。 非同期 INSERT のデータは、ClickHouse のバッファが flush されると挿入されます。これは、async_insert_max_data_size を超過した後、または最初の INSERT クエリから async_insert_busy_timeout_ms ミリ秒が経過した後のいずれかで発生します。async_insert_stale_timeout_ms が 0 以外の値に設定されている場合は、最後のクエリから async_insert_stale_timeout_ms ミリ秒後にデータが挿入されます。これらの設定を調整することで、パイプラインのエンドツーエンドのレイテンシを制御できます。バッファ flush の調整に使用できるその他の設定は こちら に記載されています。一般には、既定値のままで十分です。
適応型非同期挿入も検討してください使用する エージェント の数が少なく、スループットは低い一方で、エンドツーエンドのレイテンシ要件が厳しい場合は、adaptive asynchronous inserts が役立つことがあります。一般に、ClickHouse で見られるような高スループットのオブザーバビリティのユースケースには適していません。
最後に、ClickHouse への同期 insert に関連する従来の重複排除の挙動は、非同期挿入を使用する場合、既定では有効になりません。必要に応じて、設定 async_insert_deduplicate を参照してください。 この機能の設定に関する詳細は、ドキュメントページ または、より詳しい ブログ記事 を参照してください。

​
スケーリング

ClickStack OTel collector は、ゲートウェイのインスタンスとして機能します。詳細は collector の役割 を参照してください。これらは独立したサービスとして提供され、通常はデータセンターごと、またはリージョンごとに配置されます。単一の OTLP エンドポイントを介して、アプリケーション (またはエージェント ロールの他の collector) からイベントを受信します。通常は複数の collector インスタンスをデプロイし、標準のロードバランサーでそれらの間に負荷を分散します。 このアーキテクチャの目的は、計算負荷の高い処理をエージェントから切り離し、リソース使用量を最小限に抑えることです。これらの ClickStack ゲートウェイは、本来エージェント側で実行する必要がある変換タスクを処理できます。さらに、多数のエージェントからイベントを集約することで、ゲートウェイは大きなバッチを ClickHouse に送信でき、効率的な挿入が可能になります。エージェントや SDK ソースが追加され、イベントのスループットが増加しても、これらのゲートウェイ collector は容易にスケールできます。

​
Kafka の追加

上記のアーキテクチャでは、メッセージキューとして Kafka を使っていないことに気づく方もいるでしょう。 メッセージバッファとして Kafka キューを使うのは、ロギングアーキテクチャで広く見られる一般的な設計パターンであり、ELK スタックの普及とともに広まりました。これにはいくつかの利点があります。主な利点は、より強力なメッセージ配信保証を実現しやすくなり、バックプレッシャーにも対処しやすくなることです。メッセージは収集エージェントから Kafka に送られ、ディスクに書き込まれます。理論上、クラスター化された Kafka インスタンスは高スループットのメッセージバッファとして機能します。これは、メッセージを解析して処理するよりも、データをディスクに順次書き込むほうが計算負荷が低いためです。たとえば Elastic では、トークン化と索引付けに大きなオーバーヘッドが発生します。また、データをエージェントから切り離すことで、ソース側でのログローテーションによってメッセージが失われるリスクも抑えられます。さらに、メッセージの再生やリージョン間レプリケーションの機能も提供できるため、ユースケースによっては魅力的です。 一方で、ClickHouse はデータを非常に高速に挿入できます。標準的なハードウェアでも、1 秒あたり数百万行を処理できます。ClickHouse によるバックプレッシャーはまれです。多くの場合、Kafka キューを導入すると、アーキテクチャが複雑になり、コストも増えます。ログには銀行取引やその他のミッションクリティカルなデータと同等の配信保証は不要、という考え方を受け入れられるなら、Kafka の複雑さは避けることを推奨します。 ただし、高い配信保証や、データを再生する機能 (場合によっては複数のソース向け) が必要であれば、Kafka は有用なアーキテクチャ上の追加要素になり得ます。 この場合、OTel エージェントは Kafka exporter を介して Kafka にデータを送信するよう設定できます。一方、ゲートウェイ インスタンスは Kafka receiver を使用してメッセージを消費します。詳細については、Confluent および OTel のドキュメントを参照することを推奨します。
OTel collector の設定ClickStack OpenTelemetry collector ディストリビューションは、collector のカスタム設定 を使って Kafka に対応するよう構成できます。

​
リソースの見積もり

OTel collector のリソース要件は、イベントのスループット、メッセージのサイズ、実行される処理の量によって異なります。OpenTelemetry プロジェクトでは、リソース要件の見積もりに利用できる ベンチマーク を公開しています。 私たちの経験では、3 コアと 12GB の RAM を備えた ClickStack ゲートウェイ インスタンスは、1 秒あたり約 60k イベントを処理できます。これは、フィールド名の変更のみを行い、正規表現を使用しない最小限の処理パイプラインを前提としています。 イベントをゲートウェイに送信し、イベントにタイムスタンプを設定するだけの エージェント インスタンスについては、想定される 1 秒あたりのログ数に基づいてサイズを決めることを推奨します。以下は、出発点として使えるおおよその値です。
ログ出力レートcollector エージェント に必要なリソース
1k/秒0.2CPU, 0.2GiB
5k/秒0.5 CPU, 0.5GiB
10k/秒1 CPU, 1GiB

​
スキーマの選択: Map vs JSON

ClickStack collectorはデフォルトで、属性を Map(LowCardinality(String), String) カラムに格納するテーブルを作成します。これはオブザーバビリティのワークロードに推奨されるスキーマです。JSON 型のスキーマは、属性キーのセットが小さく安定しているワークロードで評価できるよう、ベータ版として提供されています。 詳細な比較、各方式が適しているケース、JSON 型スキーマを有効にするために必要な env vars、ならびに移行手順については、Map vs JSON type を参照してください。
最終更新日 2026年6月10日