> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending OpenTelemetry to ClickHouse Observability with Odigos

> Auto-instrument Kubernetes workloads with Odigos and export telemetry to ClickHouse Observability over OTLP

Partner Integration

> [!NOTE]
>
> **TL;DR**
>
> This guide shows you how to export Odigos telemetry to ClickHouse Observability. You'll learn how to:
>
> * Deploy Odigos on Kubernetes with Helm
> * Add sources in the Odigos UI
> * Add an OTLP HTTP destination pointed at ClickHouse Observability
> * Verify logs, metrics, and traces in ClickHouse Observability
>
> Odigos auto-instruments applications without code changes or restarts; ClickHouse Observability stores and queries the data in ClickHouse.
>
> Time required: 10–20 minutes

## What is Odigos?

[Odigos](https://odigos.io/) is an instrumentation control plane for Kubernetes and VMs that instruments applications from the kernel using **eBPF**. Because collection runs in the kernel, app overhead stays low while visibility stays high. You get production-grade OpenTelemetry traces, metrics, logs, and profiles without shipping new agents in application code or waiting on library upgrades across every service.

That eBPF layer is what makes deep, consistent telemetry possible at scale. Odigos can automatically turn on and off deeper instrumentation when needed to help debug or troubleshoot problems:

* **Code-level context** — attributes tied to functions and runtime behavior
* **HTTP traffic** — requests and responses across your services
* **Messaging systems** — payloads and messages from Kafka and similar brokers
* **Errors in detail** — stack traces when things fail
* **Custom instrumentation** — extend coverage where auto-instrumentation stops without requiring code changes or restarts

Behind the scenes, Odigos creates and manages a full OpenTelemetry pipeline for your cluster: collectors that scale with load, routing to the backends you choose, and pipeline logic you control in the UI. Define **sampling** to manage volume, **PII masking** to keep sensitive data out of exports, and **OTTL rules** to filter, transform, or enrich telemetry before it leaves the cluster.

## Why Odigos + ClickHouse Observability?

Rolling out OpenTelemetry across many services is often time consuming and only provides surface-level visibility in applications. Odigos handles eBPF instrumentation for deeper telemetry and collector operations on Kubernetes; ClickHouse Observability provides ClickHouse-backed storage and the ClickStack UI for querying telemetry at scale.

> [!TIP]
>
> **Key takeaways**
>
> * **Odigos** auto-instruments any Kubernetes workload without requiring restarts and manages OpenTelemetry pipelines automatically.
> * **ClickHouse Observability** stores logs, metrics, and traces in ClickHouse and surfaces them in the ClickStack UI.

## Prerequisites

* A ClickHouse Observability service reachable from your Kubernetes cluster. See [Getting started](https://clickhouse.com/docs/clickstack/observability/getting-started.md). For self-managed deployments, see [Self-managed setup](https://clickhouse.com/docs/clickstack/self-configured/deployment/managed.md).
* Your **OTLP HTTP endpoint** and ingestion API key from **Team Settings → Data → Managed Telemetry**. For self-managed deployments, use your standalone collector endpoint and `OTLP_AUTH_TOKEN`.
* A **Kubernetes cluster** (Linux nodes with kernel 4.18 or later for eBPF instrumentation)
* **Helm**, **kubectl**, and cluster credentials to install into `odigos-system` namespace
* An **Odigos Enterprise on-prem token** — contact the [Odigos team](https://odigos.io/) for access

## Integrate ClickHouse Observability with Odigos

**1. Deploy Odigos with Helm**

Odigos Enterprise requires an on-prem license token. Export it in your shell:

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

Alternatively, you can store the token in a Kubernetes Secret named `odigos-pro` before installing. See [Odigos Enterprise documentation](https://enterprise.docs.odigos.io/) (requires access).

Add the Odigos Helm repository and install the chart into `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
```

You can pass additional configuration overrides with `--set` flags or a custom values file (`-f`). To inspect the chart's default values, run `helm show values odigos/odigos`.

Verify Odigos pods are running:

```bash theme={null}
kubectl get pods -n odigos-system
```

**2. Add sources in the Odigos UI**

1. Port-forward the Odigos UI service:

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

2. Open [http://localhost:3000](http://localhost:3000) in your browser.
3. Go to **Sources** and select the namespaces or workloads you want to instrument.
4. Click done at the bottom, once you have marked all workloads for instrumentation.
5. Verify workloads have been instrumented successfully in the sources column.

**3. Add ClickHouse Observability as a destination in the Odigos UI**

To send telemetry, add an **OTLP HTTP** destination in Odigos. Select your deployment below.

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> ClickHouse Observability gives you an OTLP endpoint. ClickHouse handles ingestion, schemas, and compute. Point Odigos at that endpoint. You do not deploy a collector.
>
> 1. In the Odigos UI, click **Add Destination** and select **OTLP HTTP**.
> 2. Set **OTLP HTTP Endpoint** to the HTTPS endpoint from ClickHouse Cloud, including port `4318`. For example, `https://<service-id>.otel.<region>.aws.clickhouse.com:4318`.
> 3. In **Headers**, add:
>    * **Key**: `Authorization`
>    * **Value**: `Bearer <YOUR_INGESTION_API_KEY>`
> 4. Enable **Logs**, **Metrics**, and **Traces**.
> 5. Save the destination.

> [tab] Self-managed
>
> > [!TIP]
> >
> > **Alternative: write directly to ClickHouse**
> >
> > For self-managed deployments, you can use Odigos's [native **ClickHouse** destination](#native-clickhouse-destination) instead of running an OTLP collector, provided your ClickHouse service is reachable from your Kubernetes cluster. Fully managed deployments must use the managed OTLP endpoint.
>
> For a self-managed deployment, run the [ClickStack distribution of the collector in standalone mode](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#configuring-the-collector-self-configured) yourself and set the authentication token via the `OTLP_AUTH_TOKEN` environment variable when starting the container. Odigos then sends OTLP HTTP traffic to that collector with the same token in the `Authorization` header.
>
> 1. Start the ClickStack collector in standalone mode, pointing it at your ClickHouse Cloud service and securing it with an `OTLP_AUTH_TOKEN` of your choice:
>
>    ```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
>    ```
>
>    For TLS, dedicated ingestion users, and other production recommendations, see [Securing the collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#securing-the-collector-self-configured).
>
> 2. In the Odigos UI, click **Add Destination** and select **OTLP HTTP**.
>
> 3. Set **OTLP HTTP Endpoint** to the standalone collector you just started (for example, `http://my-collector.example.com:4318`).
>
> 4. In **Headers**, add:
>    * **Key**: `Authorization`
>    * **Value**: the `OTLP_AUTH_TOKEN` value you set on the collector
>
> 5. Enable **Logs**, **Metrics**, and **Traces**.
>
> 6. Save the destination.
>
> > [!NOTE]
> >
> > **Optional: Kubernetes manifest**
> >
> > You can configure the same destination with a `Destination` manifest instead of the UI. See [Configure destinations with Kubernetes manifests](#destination-manifest) in Advanced configuration.

**4. Verify telemetry in ClickHouse Observability**

1. Open the ClickStack UI:
   * **Self-managed**: open your service in the [ClickHouse Cloud console](https://console.clickhouse.cloud), then click **Launch ClickStack**. See [Navigate to the ClickStack UI](https://clickhouse.com/docs/clickstack/self-configured/deployment/managed.md) for details.
   * **Fully managed**: open the observability view for your ClickHouse Cloud service.
2. Check **Logs**, **Metrics**, and **Traces** for data from your instrumented services.
3. Filter traces by `odigos.version` to validate end-to-end export.

If data is missing, check collector logs: `kubectl logs deploy/odigos-gateway -n odigos-system`

## Advanced configuration

### Native ClickHouse destination

The native ClickHouse destination is available only for **self-managed** deployments. For **fully managed** deployments, use the **OTLP HTTP** destination with your managed endpoint.

> [tab] Self-managed
>
> When ClickHouse is directly reachable from your cluster, you can use Odigos's native **ClickHouse** destination instead of OTLP HTTP. Configure the ClickHouse endpoint, database name, and schema options in the UI or with a manifest — see [Odigos ClickHouse destination](https://docs.odigos.io/backends/clickhouse).
>
> * **Production schema**: Set `CLICKHOUSE_CREATE_SCHEME` to `false` and apply your own DDL.
> * **TLS / auth**: Use `CLICKHOUSE_TLS_ENABLED`, `CLICKHOUSE_USERNAME`, and a Kubernetes Secret for the password.
>
> **Kubernetes manifest**
>
> ```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'
> ```
>
> Save the manifest as `destination.yaml` and apply it:
>
> ```bash theme={null}
> kubectl apply -f destination.yaml
> ```
>
> #### HyperDX log normalizer
>
> For self-managed deployments that export directly to ClickHouse with Odigos's native **ClickHouse** destination, enable **HyperDX log normalizer** (`HYPERDX_LOG_NORMALIZER: true`). It parses JSON log bodies and normalizes attributes for better querying in the ClickStack UI. This setting does not apply to the fully managed OTLP destination.

### Configure destinations with Kubernetes manifests

**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'
    # Self-managed: OTLP_AUTH_TOKEN
    # ClickHouse Observability: Bearer <YOUR_INGESTION_API_KEY>
    OTLP_HTTP_HEADERS: 'Authorization:<YOUR_AUTHORIZATION_VALUE>'
```

Apply the manifest:

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

### Odigos VM Agent

The [Odigos VM Agent](https://docs.odigos.io/vmagent/overview) instruments Linux processes, systemd services, and/or docker containers using eBPF. Telemetry exports to the same destinations as cluster-based Odigos, including ClickHouse Observability over OTLP HTTP.

The VM Agent is part of Odigos Pro. See the [VM Agent overview](https://docs.odigos.io/vmagent/overview) for setup, sources, and destination configuration.

### Odigos Central

[Odigos Central](https://docs.odigos.io/central/overview) is a centralized control plane for managing instrumentation, destinations, and pipeline configuration across multiple Kubernetes clusters from one UI - instead of configuring each cluster separately.

Odigos Central is available in Odigos Enterprise. See the [Central overview](https://docs.odigos.io/central/overview) for multi-cluster management, SSO, and unified sampling rules.

## Next steps

* **Explore traces** across instrumented services in ClickHouse Observability
* **Build dashboards** for metrics Odigos exports
* **For self-managed deployments, tune ClickHouse schema and TTL** for your retention and query patterns

## Read more

* [Odigos Enterprise documentation](https://enterprise.docs.odigos.io/) (requires access)
* [Odigos ClickHouse destination](https://docs.odigos.io/backends/clickhouse)
* [Odigos VM Agent overview](https://docs.odigos.io/vmagent/overview)
* [Odigos Central overview](https://docs.odigos.io/central/overview)
* [Stop guessing in production: Full fidelity tracing at scale with ClickHouse and Odigos](https://clickhouse.com/blog/odigos-full-fidelity-tracing)
* [Odigos with ClickStack Open Source](https://clickhouse.com/docs/clickstack/integration-partners/odigos.md)

## Example destination configuration

The following screenshot shows an OTLP HTTP destination with logs, metrics, and traces enabled and a bearer token in the `Authorization` header. Replace the example endpoint and token with your service's OTLP HTTP endpoint and ingestion API key.

![Odigos OTLP HTTP destination with logs, metrics, and traces enabled, an HTTPS endpoint, and an Authorization header containing a bearer token placeholder](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/integration-partners/odigos-otlp-http-destination.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=3cc124f121ab162fbaaae542fe8ecdad)