Datadog から ClickStack への移行

オブザーバビリティプラットフォームの移行は、通常、データの保存先を変えるだけでは済みません。Datadog のエージェントや SDK は、すでに何千ものアプリケーション、ホスト、仮想マシン、Kubernetes ポッドにデプロイされていることがあります。別のバックエンドを評価する前にそれらすべてを再インストルメントしなければならないとなると、価値を生み出す前から移行は大規模なプロジェクトになってしまいます。 OpenTelemetry (OTel) collector の ClickStack ディストリビューションに組み込まれている Datadog receiver は、その初期コストを不要にします。既存の Datadog エージェントや SDK は、そのまま変更せずに動かし続けられます。Datadog にテレメトリーを送信する代わりに、送信先を receiver に向けるだけで、Datadog のネイティブな log、trace、metric のペイロードが OpenTelemetry のデータモデルに変換され、標準の collector パイプラインを通じて ClickStack に渡されます。 receiver は通常の collector パイプライン内にあるため、次のような用途に使えます。

アプリケーションコードに手を加えることなく、既存のエージェントを使って同じテレメトリーを両方のプラットフォームに送信し、Datadog と併用しながら ClickStack を評価する。
現在の収集レイヤーを維持したまま ClickStack へ移行しつつ、OpenTelemetry インストルメンテーションを段階的に導入して、移行をスムーズに進める。
長期的に 両方のスタックを並列に運用し、それぞれのプラットフォームを得意分野に応じて使い分ける。

なぜ Datadog と併用して ClickStack を運用するのか

ほとんどのチームにとって、オブザーバビリティデータを Datadog から移す最大の理由はコストです。アプリケーションの拡大や、より多くのサービスのインストルメントに伴ってログとトレースの量は増えていき、その結果、コストを増やすか、生成したテレメトリーの保持量を減らすかの選択を迫られます。さらに、こうしたコスト管理は調査時に見える範囲も狭めます。サンプリングされたトレース、索引化されていないログ、集約されたメトリクス、短い保持期間によって、本当に必要なときに得られるコンテキストが少なくなってしまいます。 ClickStack は ClickHouse 上に構築されており、大規模なログおよびトレースのワークロードでは Datadog と比べて 100 倍以上高いコスト効率を実現できる場合があります。このストレージコストの差があるからこそ、Datadog と併用して ClickStack を運用する価値があります。

より長い保持期間。 予算ではなく運用要件に合わせて保持期間を設定し、数週間後や数か月後に必要になる可能性のあるイベントも保持できます。
フルフィデリティのデータ。 すべてのログとトレースをサンプリングなしで保存できるため、一部のデータではなく完全なデータに対して調査を実行できます。
API レート制限なし。 テレメトリーを従量課金の API 経由ではなくデータベースとしてクエリでき、クエリ単位やエンドポイント単位のスロットリングもありません。
完全な SQL アクセス。 ログ、メトリクス、トレースを SQL で分析し、さらにそれらを ClickHouse にすでにあるビジネスデータやインフラストラクチャデータと join できます。
エージェント型ワークロード。 ClickStack MCPサーバーを通じて AI agents にテレメトリーを公開し、無制限の分析クエリを ClickHouse に対して直接実行できます。

フルフィデリティのテレメトリーは、特にエージェント型の調査で大きな価値を発揮します。AI agents は、調査が始まる前に破棄されたイベントについて推論することはできません。また、現在のインシデントを過去の障害、挙動の変化、長期間にわたるパターンと比較するには、十分な履歴が必要です。

Datadog receiver の仕組み

一般的な OpenTelemetry のデプロイメントでは、テレメトリーはバックエンドに到達する前に OpenTelemetry collector に送られます。collector は、agent モードの collector や、アプリケーションをインストルメントする OpenTelemetry SDKs からデータを受け取り、必要に応じてフィルタリングや変換を適用し、イベントをバッチ化して、目的の宛先にエクスポートします。 Datadog receiver は、このアーキテクチャに新たな入力経路を追加します。Datadog の agent や SDK で使われるプロトコルを理解するエンドポイントを公開し、受信した Datadog ペイロードを OpenTelemetry のデータモデルに変換します。以降は、他のテレメトリーと同様に通常の collector パイプラインを通ります。既存の Datadog エージェントは、ClickStack collector 上で稼働する receiver にログとトレースを送信するよう再設定するだけで済みます。アプリケーションは既存の Datadog SDK をそのまま使い続けられ、インフラストラクチャ全体にすでにデプロイされている agent もそのまま維持できます。 collector パイプラインでは複数のエクスポーターを利用できるため、同じテレメトリーを Datadog と ClickStack の両方に同時に送信できます。これにより、並行的な評価や長期的な並行運用が可能になります。つまり、同一のデータで両方のプラットフォームを比較したうえで、移行するかどうかを独立して判断できます。

receiverが処理する内容

receiverはDatadogのペイロードを適切なOpenTelemetry表現に変換するため、ClickStackはDatadog固有のロジックなしでデータを解釈し、相関付け、クエリできるようになります。

ログレコード。 Datadogのミリ秒タイムスタンプはナノ秒に変換され、OpenTelemetryのtimestamp、observed timestamp、body、severityの各フィールドの設定に使用されます。これにより、レコードがUnix epochとして表示されることはなくなります。
リソース属性とseverity。 info、warn、error などのDatadogのstatusは、対応するOpenTelemetryの SeverityNumber と SeverityText にマッピングされます。hostname、service name、environment、および既知のcontainer、クラウド、Kubernetesのタグは、標準のリソース属性に昇格されます。
traceとログの相関付け。 dd.trace_id と dd.span_id のフィールドはOpenTelemetryのtrace識別子とspan識別子の設定に使われ、receiverはDatadogの分割表現から完全な128ビットのtrace IDを再構築します。これはデフォルトで有効になっており、Datadog由来のログやspanを、OpenTelemetryでインストルメントされたserviceと相関付けられるようにします。
構造化JSONログ。 デフォルトで有効な decode_json_message オプションは、通常Datadog backendで行われるJSON処理を実行し、body、timestamp、severity、trace識別子、resourceフィールド、および残りの属性を抽出します。
現在のエージェントとの互換性。 Datadog Agent 7.59以降では、HTTPペイロードはデフォルトでZstandard圧縮されます。receiverはgzipに加えてZstandardもサポートしているため、現在のエージェントはペイロードが拒否されることなく接続できます。

これらの変更はClickStack collector distributionに含まれており、自動構成されます。また、OpenTelemetry Collector Contrib プロジェクトでも利用できます。

Datadog receiver を有効にする

Datadog receiver は、8126 ポートで待ち受ける ClickStack 版の OpenTelemetry Collector に含まれています。デフォルトでは無効になっており、ENABLE_DATADOG_RECEIVER 環境変数で有効にできます。有効にしたら、Datadog エージェントの送信先をこの receiver に設定し、ClickStack のインジェストキーで認証します。このキーの取得方法はデプロイ方法によって異なります。Managed ClickStack ではスタンドアロンの collector を実行し、起動時に自分でキーを設定します。一方、Open Source ClickStack ではキーが自動生成され、ClickStack のインターフェイス (HyperDX) からコピーします。以下からご利用のデプロイ方法を選択してください。

マネージド ClickStack
オープンソース版 ClickStack

Managed ClickStack では、ClickHouse Cloud サービスにインジェストするスタンドアロンの ClickStack collector をデプロイします。collector は起動時に、自分で選んだ認証トークンで保護し、その同じトークンを Datadog agent の API key として再利用します。

receiver を有効にして collector をデプロイする

ClickStack OpenTelemetry collector と標準の OpenTelemetry collector の違いDatadog receiver は、ClickStack 版の OpenTelemetry collector に組み込まれており、事前設定済みです。標準の OpenTelemetry Collector Contrib distribution を使用する場合は、receiver を自分で設定する必要があります。receiver に対する変更や改善はすべてアップストリームに反映されているため、そちらでも利用できます。設定オプションについては、Datadog receiver README を参照してください。

standalone ClickStack collector を実行し、ClickHouse Cloud サービスを指定します。ENABLE_DATADOG_RECEIVER=true で Datadog receiver を有効にし、ポート 8126 を公開して、独自の OTLP_AUTH_TOKEN を設定することでインジェストを保護します。

export CLICKHOUSE_ENDPOINT=<HTTPS_ENDPOINT>
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>
export OTLP_AUTH_TOKEN="a_very_secure_string"

docker run --name clickstack-collector \
  -e ENABLE_DATADOG_RECEIVER=true \
  -e OTLP_AUTH_TOKEN=${OTLP_AUTH_TOKEN} \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=${CLICKHOUSE_USER} \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8126:8126 \
  clickhouse/clickstack-otel-collector:latest

これで receiver は http://localhost:8126 で利用可能になり、OTLP_AUTH_TOKEN のトークンを Datadog agent に渡す key として使用します。Helm での同等の設定を含め、collector の保護について詳しくは、“collector を保護する” を参照してください。

Datadog agent を設定する

/opt/datadog-agent/etc/datadog.yaml の agent 設定ファイルを更新し、logs、traces、メトリクスを receiver に送信します。OTLP_AUTH_TOKEN の値を API key として使用し、各宛先を receiver endpoint に向けます。

api_key: "<YOUR_OTLP_AUTH_TOKEN>"

# メトリクスの宛先
dd_url: "http://localhost:8126"

# ClickStack は現在 Datadog v2 metrics intake をサポートしています。
use_v3_api:
  series:
    enabled: false

# trace の宛先
apm_config:
  enabled: true
  apm_dd_url: "http://localhost:8126"

# log の宛先
logs_enabled: true

logs_config:
  logs_dd_url: "http://localhost:8126"
  force_use_http: true

# これらは Datadog の backend を必要としますが、ここでは使用しないため無効にします。
remote_updates: false

remote_configuration:
  enabled: false

この設定により、次のようになります。

メトリクス、traces、logs は Datadog ではなく receiver に送信されます。
ClickStack は Datadog v2 metrics endpoint をサポートしているため、v3 metrics intake は無効になります。
Datadog backend に依存する remote updates と remote configuration は無効になります。

agent を再起動する

Datadog agent を再起動して、新しい設定を反映させます。macOS の場合:

sudo launchctl kickstart -k system/com.datadoghq.agent

これで agent からのテレメトリーが ClickStack に送られ、HyperDX で確認できるようになります。

Open Source ClickStack では、stack のデプロイ時に生成されるインジェスト key を使用して、collector がその endpoints を保護します。receiver を有効にし、ClickStack のインターフェイス (HyperDX) からその key をコピーして、Datadog agent の API key として使用します。

receiver を有効にした collector を起動する

以下の例では、all-in-one イメージを使用します。別の distribution モデルを使用している場合は、collector を実行しているコンテナーにも同じ flag が適用されていることを確認してください。ENABLE_DATADOG_RECEIVER=true を設定し、ポート 8126 を公開します。

docker run --name clickstack \
  -p 8080:8080 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8126:8126 \
  -e ENABLE_DATADOG_RECEIVER=true \
  clickhouse/clickstack-all-in-one:latest

receiver は http://localhost:8126 で利用可能になります。

ローカルの Datadog agent を実行している場合Datadog agent もポート 8126 で待ち受けます。agent が collector と同じ host で動作している場合は、競合を避けるため、collector を別の host ポートにマッピングしてください。たとえば -p 18126:8126 を使用し、agent の接続先もそのポートに変更します。

残りのセットアップ手順は、open source getting started guideの説明に従って完了してください。

インジェスト API key をコピーする

ClickStack のインターフェイス (HyperDX) で、左下のユーザーを選択し、Team Settings > API Keys に移動して、Ingestion API Key をコピーします。

Datadog agent を設定する

/opt/datadog-agent/etc/datadog.yaml の agent 設定ファイルを更新し、logs、traces、メトリクスを receiver に送信するようにします。ClickStack のインジェスト key を API key として使用し、各宛先が receiver endpoint を指すように設定してください。

api_key: "<YOUR_CLICKSTACK_INGESTION_KEY>"

# Metrics destination
dd_url: "http://localhost:8126"

# ClickStack currently supports the Datadog v2 metrics intake.
use_v3_api:
  series:
    enabled: false

# Trace destination
apm_config:
  enabled: true
  apm_dd_url: "http://localhost:8126"

# Log destination
logs_enabled: true

logs_config:
  logs_dd_url: "http://localhost:8126"
  force_use_http: true

# These require Datadog's backend, which we aren't using, so we disable them.
remote_updates: false

remote_configuration:
  enabled: false

この設定により、次のようになります。

メトリクス、traces、logs は Datadog ではなく receiver に送信されます。
receiver は Datadog v2 metrics endpoint をサポートしているため、v3 metrics intake は無効になります。
Datadog backend に依存する remote updates と remote configuration は無効になります。

agent を再起動する

新しい設定を反映するため、Datadog agent を再起動します。macOS の場合:

sudo launchctl kickstart -k system/com.datadoghq.agent

これで agent からのテレメトリーが ClickStack に取り込まれ、HyperDX で確認できるようになります。

実践例

以下の例では、サンプルアプリケーションを使って、インストルメントされたアプリから Datadog エージェントを経由して ClickStack に至るまでの一連の流れを示します。

サンプルアプリをクローンして実行する

この例では、datadog-instrumentation ブランチで Datadog によりインストルメントされた Hacker News demo app を使用します。まず、そのブランチをクローンします。

git clone --branch datadog-instrumentation https://github.com/ClickHouse/hn-news-analyzer.git

アプリの実行方法は、README の手順を参照してください。

receiver を有効にして ClickStack を起動する

Datadog receiver を有効にして all-in-one イメージを起動します。ここでは、同じく 8126 を使用するローカルの Datadog エージェントと競合しないよう、receiver をホストのポート 18126 にマッピングします。

docker run --name clickstack \
  -p 8080:8080 \
  -p 8123:8123 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 127.0.0.1:18126:8126 \
  -e ENABLE_DATADOG_RECEIVER=true \
  clickhouse/clickstack-all-in-one:latest

receiver は http://127.0.0.1:18126 で利用できます。

Datadog エージェントをインストールして設定する

Datadog エージェントをインストールします。macOS の場合は次を実行します。

DD_SITE="datadoghq.com" bash -c "$(curl -L https://install.datadoghq.com/scripts/install_mac_os.sh)"

/opt/datadog-agent/etc/datadog.yaml を更新して、ポート 18126 の receiver を参照するよう設定し、API key として ClickStack のインジェストキーを使用します。その後、agent を再起動します。

sudo launchctl kickstart -k system/com.datadoghq.agent

agent の完全な設定例とインジェストキーの確認場所については、Datadog receiver を有効にするを参照してください。

ClickStack でテレメトリーを確認する

http://localhost:8080 で HyperDX インターフェイスを開き、Datadog エージェントから収集されたトレース、ログ、メトリクスを確認します。

現在移行できるもの

Datadog receiver は OpenTelemetry Collector Contrib の alpha コンポーネントであり、ClickStack collector ディストリビューションでは Experimental とされているため、有効にするにはフィーチャーフラグが必要です。この receiver は ログとトレース のワークロードで広範にテストされており、これらのシグナルで ClickStack を評価する際に推奨されます。メトリクス も動作しますが、さらなるテストと開発が必要です。現在、この receiver は Datadog の v1 および v2 のメトリクス取り込み endpoint をサポートしており、新しい protocol version を使用する Datadog エージェントは、サポート対象の endpoint 経由でメトリクスを送信するよう明示的に設定する必要があります。現時点では、この receiver により、アプリケーションがすでに Datadog SDKs を使用している場合や、インフラストラクチャで Datadog エージェントが稼働している場合に、ClickStack を手早く評価できます。両方のパイプラインを並列に実行し、データが ClickStack でどのように表現され、どのようにクエリできるかを検証したうえで、より広範な移行に進むかどうかを判断してください。評価の結果、明確なメリットが確認できた場合は、同じアーキテクチャで段階的に移行することも可能です。既存の Datadog インストルメンテーションはそのまま維持しつつ、各サービスを時間をかけて OpenTelemetry へ移行できます。

機能

ガイド

なぜ Datadog と併用して ClickStack を運用するのか

Datadog receiver の仕組み

receiverが処理する内容

Datadog receiver を有効にする

実践例

現在移行できるもの

​なぜ Datadog と併用して ClickStack を運用するのか

​Datadog receiver の仕組み

​receiverが処理する内容

​Datadog receiver を有効にする

​実践例

​現在移行できるもの

なぜ Datadog と併用して ClickStack を運用するのか

Datadog receiver の仕組み

receiverが処理する内容

Datadog receiver を有効にする

実践例

現在移行できるもの