Odigos を使用して OpenTelemetry を ClickStack へ送信する

Odigos で Kubernetes ワークロードを自動インストルメントし、OTLP 経由でテレメトリーを ClickStack にエクスポート

要点

このガイドでは、Odigos のテレメトリーを ClickStack にエクスポートする方法を説明します。ここでは、次の内容を学びます。

• Helm を使用して Kubernetes に Odigos をデプロイする
• Odigos UI でソースを追加する
• ClickStack を宛先とする OTLP HTTP 宛先を追加する
• ClickStack でログ、メトリクス、トレースを確認する

Odigos は、コードを変更したり再起動したりすることなく、アプリケーションを自動的にインストルメントします。ClickStack はそのデータを ClickHouse に保存し、クエリできます。

所要時間: 10～20 分

​

Odigosとは？

Odigos は、eBPF を使ってカーネルからアプリケーションをインストルメントする、Kubernetes と VM 向けのインストルメンテーション制御プレーンです。収集はカーネル内で実行されるため、アプリへのオーバーヘッドを低く抑えながら、高い可観測性を確保できます。アプリケーションコードに新たなエージェントを組み込んだり、すべてのサービスでライブラリのアップグレードを待ったりすることなく、本番環境で利用できる OpenTelemetry のトレース、メトリクス、ログ、プロファイルを取得できます。

この eBPF レイヤーこそが、大規模環境でも深く一貫したテレメトリーを可能にしています。Odigos は必要に応じて、より詳細なインストルメンテーションを自動で有効化・無効化し、問題のデバッグやトラブルシューティングを支援します。

• コードレベルのコンテキスト — 関数やランタイムの挙動にひも付く属性
• HTTP トラフィック — サービス間のリクエストとレスポンス
• メッセージングシステム — Kafka や同様のブローカーからのペイロードやメッセージ
• 詳細なエラー情報 — 障害発生時のスタックトレース
• カスタム インストルメンテーション — 自動インストルメンテーションでカバーできない範囲を、コード変更や再起動なしで拡張

Odigos は内部で、クラスター向けの完全な OpenTelemetry パイプライン を作成・管理します。これには、負荷に応じてスケールする collector、選択したバックエンドへのルーティング、そして UI から制御できる パイプライン ロジックが含まれます。サンプリング を定義してデータ量を管理し、PII マスキング で機微なデータがエクスポートに含まれないようにし、OTTL ルール でテレメトリーがクラスター外に出る前にフィルタリング、変換、拡充を行えます。

​

なぜ Odigos + ClickStack なのか

多数のサービスに OpenTelemetry を展開するには時間がかかることが多く、アプリケーション内部の挙動も表面的にしか把握できません。Odigos は Kubernetes 上で、より深いテレメトリー取得のための eBPF インストルメンテーションと collector の運用を担います。ClickStack は ClickHouse を基盤としたストレージと、大規模なテレメトリーをクエリできる HyperDX UI を提供します。

主なポイント

• Odigos は再起動なしであらゆる Kubernetes ワークロードを自動的にインストルメントし、OpenTelemetry パイプラインを自動で管理します。
• ClickStack はログ、メトリクス、トレースを ClickHouse に保存し、HyperDX に表示します。

​

前提条件

• Kubernetes クラスターからアクセス可能な ClickStack がインストールされていること。Open Source ClickStack を使い始める または Managed ClickStack の Getting Started を参照してください。
• ClickStack の OTLP HTTP エンドポイント (ポート 4318) と、Odigos が Authorization ヘッダーで渡す認証値。オープンソース版 ClickStack の場合、これは HyperDX UI の Team Settings → API Keys にある APIインジェストキー です。Managed ClickStack の場合、これは独自のスタンドアロン ClickStack collector の起動時に設定する OTLP_AUTH_TOKEN です。
• Kubernetes クラスター (eBPF インストルメンテーションには、カーネル 4.18 以降の Linux ノードが必要)
• odigos-system ネームスペースにインストールするための Helm、kubectl、およびクラスター認証情報
• Odigos Enterprise オンプレミス トークン — アクセスするには Odigos チーム にお問い合わせください

​

ClickStackとOdigosを統合する

1. ​

   HelmでOdigosをデプロイする

   Odigos Enterprise にはオンプレミス用のライセンス トークンが必要です。シェルでこれをエクスポートします:

   export ODIGOS_ONPREM_TOKEN="<your-enterprise-token>"
   

   または、インストール前に、odigos-pro という名前の Kubernetes Secret にトークンを保存しておくこともできます。詳しくは、Odigos Enterprise installation を参照してください。

   Odigos の Helm リポジトリを追加し、チャートを odigos-system にインストールします。

   helm repo add odigos https://odigos-io.github.io/odigos/
   helm repo update
   
   helm upgrade --install odigos odigos/odigos \
     --namespace odigos-system \
     --create-namespace \
     --set onPremToken=$ODIGOS_ONPREM_TOKEN
   

   --set フラグまたはカスタム values ファイル (-f) を使用して、追加の設定上書きを指定できます。チャートのデフォルト値は、GitHub 上の helm/odigos/values.yaml にあります。

   Odigos のポッドが実行中であることを確認してください。

   kubectl get pods -n odigos-system
   
2. ​

   Odigos UI でソースを追加する

   1. Odigos UI のサービスをポートフォワードします:

   kubectl port-forward svc/ui -n odigos-system 3000:3000
   

   2. ブラウザで http://localhost:3000 を開きます。
   3. SOURCES に移動し、インストルメントするネームスペースまたはワークロードを選択します。
   4. すべてのワークロードをインストルメンテーション対象としてマークしたら、画面下部の done をクリックします。
   5. SOURCES 列で、ワークロードが正常にインストルメントされていることを確認します。
3. ​

   Odigos UI で ClickStack を宛先として追加する

   ClickStack にテレメトリーを送信するには、Odigos で OTLP HTTP 宛先を追加します。具体的な設定内容は、ClickStack のデプロイ方法によって異なります。Open Source ClickStack では OpenTelemetry collector が同梱されており、インジェスト key は HyperDX UI で自動的に生成されます。Managed ClickStack では、独自の standalone ClickStack collector を実行し、コンテナーの起動時に認証トークンを自分で設定します。

   代替手段: ClickHouse に直接書き込む

   Kubernetes クラスターから ClickHouse にアクセスできる場合は、OTLP collector を完全に省略して、代わりに Odigos の native ClickHouse 宛先 を使用できます。これは Open Source ClickStack と Managed ClickStack のどちらでも利用できます。

   Open Source ClickStack

   Open Source ClickStack では、たとえば all-in-one イメージを使用する場合、ゲートウェイ OpenTelemetry collector が含まれており、インジェスト API key は HyperDX によって自動的に生成されます。

   1. Odigos UI で Add Destination をクリックし、OTLP HTTP を選択します。
   2. OTLP HTTP Endpoint に ClickStack collector を設定します (例: http://clickstack.example.com:4318) 。エンドポイントの詳細については、OpenTelemetry でのインジェスト を参照してください。
   3. ClickStack UI の Team Settings → API Keys で API Ingestion Key をコピーします。
   4. Headers に以下を追加します。
      • Key: Authorization
      • Value: API Ingestion Key
   5. Logs、Metrics、Traces を有効にします。
   6. 宛先を保存します。

   Managed ClickStack

   Managed ClickStack にはホスト型の OpenTelemetry collector は含まれておらず、UI にインジェスト key も表示されません。代わりに、自身で standalone モードの ClickStack distribution の collector を実行し、コンテナーの起動時に OTLP_AUTH_TOKEN 環境変数で認証トークンを設定します。すると Odigos は、その collector に対して同じトークンを Authorization header に含めて OTLP HTTP トラフィックを送信します。

   1. standalone モードで ClickStack collector を起動し、ClickHouse Cloud service を指定し、任意の 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 \
        -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 \
        clickhouse/clickstack-otel-collector:latest
      

      TLS、専用のインジェスト users、その他の本番環境向けの推奨事項については、collector の保護 を参照してください。

   2. Odigos UI で Add Destination をクリックし、OTLP HTTP を選択します。

   3. OTLP HTTP Endpoint に、先ほど起動した standalone collector を設定します (例: http://my-collector.example.com:4318) 。

   4. Headers に以下を追加します。

      • Key: Authorization
      • Value: collector に設定した OTLP_AUTH_TOKEN の値

   5. Logs、Metrics、Traces を有効にします。

   6. 宛先を保存します。

   任意: Kubernetes manifest

   UI の代わりに Destination manifest を使って同じ宛先を設定することもできます。Advanced configuration の Kubernetes manifest を使用した宛先の設定 を参照してください。

4. ​

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

   1. ClickStack UI (HyperDX) を開きます。
      • Open Source ClickStack: たとえば、all-in-one イメージでは http://<host>:8080 です。
      • Managed ClickStack: ClickHouse Cloud console でサービスを開き、Launch ClickStack をクリックします。詳しくは ClickStack UI に移動する を参照してください。
   2. Logs、Metrics、Traces を確認し、インストルメントしたサービスからのデータがあることを確認します。
   3. odigos.version でトレースを絞り込み、エンドツーエンドでエクスポートされていることを検証します。

   データが見つからない場合は、collector のログを確認してください: kubectl logs deploy/odigos-gateway -n odigos-system

​

詳細設定

​

HyperDX ログノーマライザー

Odigos のネイティブ ClickHouse 宛先を使用して ClickHouse に直接エクスポートする場合 (ClickStack への OTLP HTTP ではなく) 、HyperDX ログノーマライザー (HYPERDX_LOG_NORMALIZER: true) を有効にしてください。これにより、JSON 形式のログ本文が解析され、属性が正規化されるため、ClickStack UI でより適切にクエリできるようになります。

​

ネイティブ ClickHouse 宛先

クラスターから ClickHouse に直接アクセスできる場合は、OTLP HTTP の代わりに Odigos のネイティブ ClickHouse 宛先を使用できます。ClickHouse のエンドポイント、データベース名、スキーマオプションは、UI またはマニフェストで設定します。詳しくは Odigos ClickHouse 宛先 を参照してください。

• 本番環境のスキーマ: CLICKHOUSE_CREATE_SCHEME を false に設定し、独自の DDL を適用してください。
• TLS / 認証: CLICKHOUSE_TLS_ENABLED と CLICKHOUSE_USERNAME を使用し、パスワードは Kubernetes Secret で指定します。

​

Kubernetes のマニフェストで宛先を設定する

OTLP HTTP (ClickStack)

apiVersion: odigos.io/v1alpha1
kind: Destination
metadata:
  name: clickstack
  namespace: odigos-system
spec:
  type: otlphttp
  destinationName: otlphttp
  signals:
    - TRACES
    - METRICS
    - LOGS
  data:
    OTLP_HTTP_ENDPOINT: 'http://clickstack.example.com:4318'
    # オープンソース ClickStack の API インジェストキー、または Managed ClickStack の場合は OTLP_AUTH_TOKEN
    OTLP_HTTP_HEADERS: 'Authorization:<YOUR_AUTHORIZATION_VALUE>'

ClickHouse (直接接続)

apiVersion: odigos.io/v1alpha1
kind: Destination
metadata:
  name: clickhouse
  namespace: odigos-system
spec:
  type: clickhouse
  destinationName: clickhouse
  signals:
    - TRACES
    - METRICS
    - LOGS
  data:
    CLICKHOUSE_ENDPOINT: 'http://clickstack.example.com:8123'
    CLICKHOUSE_DATABASE_NAME: 'otel'
    CLICKHOUSE_CREATE_SCHEME: 'true'

マニフェストを適用します:

kubectl apply -f destination.yaml

​

Odigos VM エージェント

Odigos VM Agent は、eBPF を使用して Linux プロセス、systemd サービス、および/または Docker コンテナーをインストルメントします。テレメトリーは、OTLP HTTP 経由の ClickStack を含め、クラスターベースの Odigos と同じ宛先にエクスポートされます。

VM Agent は Odigos Pro の一部です。セットアップ、ソース、宛先の設定については、VM Agent の概要を参照してください。

​

Odigos Central

Odigos Central は、一元管理されたコントロールプレーンであり、各クラスターを個別に設定する代わりに、1 つの UI から複数の Kubernetes クラスターにまたがるインストルメンテーション、宛先、パイプライン設定を管理できます。

Odigos Central は Odigos Enterprise で利用できます。マルチクラスター管理、SSO、統合されたサンプリングルールについては、Central の概要 を参照してください。

​

次のステップ

• ClickStack で、インストルメント済みの各サービスのトレースを確認する
• Odigos がエクスポートしたメトリクスのダッシュボードを作成する
• 保持期間やクエリパターンに合わせて ClickHouse のスキーマと有効期限 (TTL) を調整する

​

関連情報

• Odigos Enterprise のインストール
• Odigos ClickHouse 宛先
• Odigos VM Agent 概要
• Odigos Central 概要
• 本番環境での当て推量をやめる: ClickHouse と Odigos で実現する大規模なフルフィデリティトレーシング
• Open Source ClickStack を使い始める