OpenTelemetry によるデータインジェスト

ClickStack のための OpenTelemetry によるデータインジェスト - The ClickHouse Observability Stack

すべてのデータは OpenTelemetry (OTel) collector インスタンス経由で ClickStack に取り込まれます。このインスタンスは、ログ、メトリクス、トレース、セッションデータの主要なエントリポイントとして機能します。このインスタンスには、collector の公式 ClickStack distribution を使用することを推奨します。

ClickStack のマネージド版も利用できます。詳しくは Managed ClickStack を参照してください。

ユーザーは、language SDKs から、またはインフラストラクチャのメトリクスやログを収集するデータ収集エージェント (agent ロールの OTel collectors や、Fluentd や Vector などのその他の技術) を通じて、この collector にデータを送信します。OpenTelemetry パイプラインのマネージド運用を求めるチーム向けに、Bindplane は、ClickStack へのネイティブな宛先を備えた OpenTelemetry ネイティブのソリューションを提供しており、テレメトリーの収集、処理、ルーティングを簡素化します。

​

OpenTelemetry データの送信

Managed ClickStack

​

ClickStack OpenTelemetry collector のインストール

Managed ClickStack にデータを送信するには、OTel collector をゲートウェイ ロールでデプロイする必要があります。OTel 互換のインストルメンテーションは、HTTP または gRPC 経由の OTLP でこの collector にイベントを送信します。

ClickStack OpenTelemetry collector の使用を推奨します

これにより、標準化されたインジェスト、強制されたスキーマ、そして ClickStack UI (HyperDX) とのそのまま使える互換性のメリットを得られます。デフォルトのスキーマを使用すると、ログソースの自動検出と事前設定済みのカラムマッピングが有効になります。

詳細は”collector のデプロイ”を参照してください。

​

collector へのデータ送信

Managed ClickStack にデータを送信するには、OpenTelemetry インストルメンテーションの送信先を、OpenTelemetry collector が提供する次のエンドポイントに設定してください。

• HTTP (OTLP): http://localhost:4318
• gRPC (OTLP): localhost:4317

OpenTelemetry をサポートするlanguage SDKsやテレメトリーライブラリでは、アプリケーションで OTEL_EXPORTER_OTLP_ENDPOINT 環境変数を設定するだけで済みます。

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

agent ロールで OTel collector の contrib ディストリビューション をデプロイする場合は、OTLP エクスポーターを使用して ClickStack collector に送信できます。この構造化ログファイルを取り込む agent の設定例を以下に示します。

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP設定
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # gRPC設定（代替）
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # 同一ホスト上で2つのcollectorが動作するため変更
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

オープンソース版 ClickStack

ClickStack OpenTelemetry collector は、以下を含むほとんどの ClickStack ディストリビューションに含まれています。

• All-in-One
• Docker Compose
• Helm

​

ClickStack OpenTelemetry collector のインストール

ClickStack OTel collector は、スタック内の他のコンポーネントとは独立したスタンドアロン構成でデプロイすることもできます。

HyperDX-only ディストリビューションを使用している場合は、データを ClickHouse に取り込む仕組みを自分で用意する必要があります。これには、次の方法があります。

• 独自の OpenTelemetry collector を実行し、送信先として ClickHouse を設定する - 詳細は以下を参照してください。
• Vector、Fluentd などの代替ツール、またはデフォルトの OTel contrib collector distribution を使って、ClickHouse に直接送信する。

ClickStack OpenTelemetry collector の使用を推奨します

これにより、標準化されたインジェスト、スキーマの適用、そして HyperDX UI との即時互換性のメリットを得られます。デフォルトのスキーマを使用すると、ログソースの自動検出と事前設定済みのカラムマッピングが有効になります。

詳細については、“collector のデプロイ” を参照してください。

​

collector にデータを送信する

ClickStack にデータを送信するには、OpenTelemetry インストルメンテーションの送信先を、OpenTelemetry Collector が提供する次のエンドポイントに設定します。

• HTTP (OTLP): http://localhost:4318
• gRPC (OTLP): localhost:4317

OpenTelemetry をサポートする language SDKs やテレメトリーライブラリでは、アプリケーションで OTEL_EXPORTER_OTLP_ENDPOINT 環境変数を設定するだけで利用できます。

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

さらに、APIインジェストキーを含む Authorization ヘッダーが必要です。このキーは、HyperDX アプリの Team Settings → API Keys で確認できます。

言語 SDK では、これは init 関数で設定することも、OTEL_EXPORTER_OTLP_HEADERS 環境変数で設定することもできます。例:

OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'

エージェントでも同様に、あらゆる OTLP 通信にこの Authorization ヘッダーを含める必要があります。たとえば、エージェントの役割で OTel collector の contrib ディストリビューション をデプロイする場合は、OTLP エクスポーターを使用できます。この構造化ログファイルを取り込むエージェント設定の例を以下に示します。認可用のキーを指定する必要がある点に注意してください。<YOUR_API_INGESTION_KEY> を参照してください。

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP セットアップ
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # gRPC セットアップ（代替）
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # 同一ホスト上で2つのcollectorが稼働するため変更
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]