> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const PartnerBadge = () => {
  return <div className="PartnerBadge">
            <div className="PartnerBadgeIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <polyline points="12.5 9.5 10 12 6 11 2.5 8.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1" />
                    <polyline points="4.54 4.41 8 3.5 11.46 4.41" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1" />
                    <path d="M2.15,3.78 L0.55,6.95 A0.5,0.5 0,0,0 0.77,7.62 L2.5,8.5 L4.54,4.41 L2.82,3.55 A0.5,0.5 0,0,0 2.15,3.78 Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1" />
                    <path d="M13.5,8.5 L15.23,7.62 A0.5,0.5 0,0,0 15.45,6.95 L13.85,3.78 A0.5,0.5 0,0,0 13.18,3.55 L11.46,4.41 Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1" />
                    <path d="M11.5,4.5 L9,4.5 L6.15,7.27 A0.5,0.5 0,0,0 6.24,8.05 C7.33,8.74 8.81,8.72 10,7.5 L12.5,9.5 L13.5,8.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1" />
                    <polyline points="7.75 13.5 5.15 12.85 3.5 11.67" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1" />
                </svg>
            </div>
            Partner Integration
        </div>;
};

<Info>
  **要点**

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

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

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

  所要時間: 10～20 分
</Info>

<div id="what-is-odigos">
  ## Odigosとは？
</div>

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

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

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

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

<div id="why-odigos-clickstack">
  ## なぜ Odigos + ClickStack なのか
</div>

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

<Tip>
  **主なポイント**

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

<div id="prerequisites">
  ## 前提条件
</div>

* Kubernetes クラスターからアクセス可能な **ClickStack** がインストールされていること。[Open Source ClickStack を使い始める](/ja/clickstack/getting-started/oss) または [Managed ClickStack の Getting Started](/ja/clickstack/getting-started/managed) を参照してください。
* 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 チーム](https://odigos.io/) にお問い合わせください

<div id="integrate-odigos-clickstack">
  ## ClickStackとOdigosを統合する
</div>

<Steps>
  <Step>
    #### HelmでOdigosをデプロイする

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

    ```bash theme={null}
    export ODIGOS_ONPREM_TOKEN="<your-enterprise-token>"
    ```

    または、インストール前に、`odigos-pro` という名前の Kubernetes Secret にトークンを保存しておくこともできます。詳しくは、[Odigos Enterprise installation](https://docs.odigos.io/enterprise/setup/installation) を参照してください。

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

    ```bash theme={null}
    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](https://github.com/odigos-io/odigos/blob/main/helm/odigos/values.yaml) にあります。

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

    ```bash theme={null}
    kubectl get pods -n odigos-system
    ```
  </Step>

  <Step>
    #### Odigos UI でソースを追加する

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

    ```bash theme={null}
    kubectl port-forward svc/ui -n odigos-system 3000:3000
    ```

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

  <Step>
    #### Odigos UI で ClickStack を宛先として追加する

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

    <Tip>
      **代替手段: ClickHouse に直接書き込む**

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

    <Tabs>
      <Tab title="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 でのインジェスト](/ja/clickstack/ingesting-data/opentelemetry#sending-data-to-collector-oss) を参照してください。
        3. ClickStack UI の **Team Settings → API Keys** で API Ingestion Key をコピーします。
        4. **Headers** に以下を追加します。
           * **Key**: `Authorization`
           * **Value**: API Ingestion Key
        5. **Logs**、**Metrics**、**Traces** を有効にします。
        6. 宛先を保存します。
      </Tab>

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

        1. standalone モードで ClickStack collector を起動し、ClickHouse Cloud service を指定し、任意の `OTLP_AUTH_TOKEN` で保護します。

           ```shell theme={null}
           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 の保護](/ja/clickstack/ingesting-data/collector#securing-the-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. 宛先を保存します。

        <Info>
          **任意: Kubernetes manifest**

          UI の代わりに `Destination` manifest を使って同じ宛先を設定することもできます。Advanced configuration の [Kubernetes manifest を使用した宛先の設定](#destination-manifest) を参照してください。
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step>
    #### ClickStack でテレメトリーを確認する

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

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

<div id="advanced-configuration">
  ## 詳細設定
</div>

<div id="hyperdx-log-normalizer">
  ### HyperDX ログノーマライザー
</div>

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

<div id="native-clickhouse-destination">
  ### ネイティブ ClickHouse 宛先
</div>

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

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

<div id="destination-manifest">
  ### Kubernetes のマニフェストで宛先を設定する
</div>

**OTLP HTTP (ClickStack)**

```yaml theme={null}
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 (直接接続) **

```yaml theme={null}
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'
```

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

```bash theme={null}
kubectl apply -f destination.yaml
```

<div id="odigos-vm-agent">
  ### Odigos VM エージェント
</div>

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

VM Agent は Odigos Pro の一部です。セットアップ、ソース、宛先の設定については、[VM Agent の概要](https://docs.odigos.io/vmagent/overview)を参照してください。

<div id="odigos-central">
  ### Odigos Central
</div>

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

Odigos Central は Odigos Enterprise で利用できます。マルチクラスター管理、SSO、統合されたサンプリングルールについては、[Central の概要](https://docs.odigos.io/central/overview) を参照してください。

<div id="next-steps">
  ## 次のステップ
</div>

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

<div id="read-more">
  ## 関連情報
</div>

* [Odigos Enterprise のインストール](https://docs.odigos.io/enterprise/setup/installation)
* [Odigos ClickHouse 宛先](https://docs.odigos.io/backends/clickhouse)
* [Odigos VM Agent 概要](https://docs.odigos.io/vmagent/overview)
* [Odigos Central 概要](https://docs.odigos.io/central/overview)
* [本番環境での当て推量をやめる: ClickHouse と Odigos で実現する大規模なフルフィデリティトレーシング](https://clickhouse.com/blog/odigos-full-fidelity-tracing)
* [Open Source ClickStack を使い始める](/ja/clickstack/getting-started/oss)