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

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

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

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

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

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

• 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 チーム にお問い合わせください

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

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

kubectl get pods -n odigos-system

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

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

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

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

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

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

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 を使い始める