Skip to content

Commit 739d11d

Browse files
locadex-agent[bot]locadex-agent[bot]
committed
Merge remote-tracking branch 'origin/main' into locadex/parallel/t9n-main-mtlkv0dh97mm5xszdcmdetec
2 parents 9c824db + 96d397d commit 739d11d

3 files changed

Lines changed: 284 additions & 0 deletions

File tree

‎docs/use-cases/observability/clickstack/integration-partners/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ ClickStack provides the core building blocks of modern observability, bringing t
1313
| Section | Description |
1414
|------|-------------|
1515
| [Bindplane](/use-cases/observability/clickstack/integration-partners/bindplane) | Bindplane is an OpenTelemetry-native telemetry pipeline that provides centralized management for OpenTelemetry Collectors. |
16+
| [Odigos](/use-cases/observability/clickstack/integration-partners/odigos) | Odigos combines eBPF and OpenTelemetry to deliver deeper distributed traces with dramatically lower overhead than bytecode agents. |

‎docs/use-cases/observability/clickstack/integration-partners/odigos.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
---
2+
slug: /use-cases/observability/clickstack/integration-partners/odigos
3+
title: 'Sending OpenTelemetry to ClickStack with Odigos'
4+
sidebar_label: 'Odigos'
5+
pagination_prev: null
6+
pagination_next: null
7+
description: 'Auto-instrument Kubernetes workloads with Odigos and export telemetry to ClickStack over OTLP'
8+
doc_type: 'guide'
9+
keywords: ['Odigos', 'ClickStack', 'ClickHouse', 'OpenTelemetry', 'eBPF', 'auto-instrumentation']
10+
---
11+
12+
import PartnerBadge from '@theme/badges/PartnerBadge';
13+
import Tabs from '@theme/Tabs';
14+
import TabItem from '@theme/TabItem';
15+
16+
<PartnerBadge/>
17+
18+
:::note[TL;DR]
19+
This guide shows you how to export Odigos telemetry to ClickStack. You'll learn how to:
20+
21+
- Deploy Odigos on Kubernetes with Helm
22+
- Add sources in the Odigos UI
23+
- Add an OTLP HTTP destination pointed at ClickStack
24+
- Verify logs, metrics, and traces in ClickStack
25+
26+
Odigos auto-instruments applications without code changes nor restarts; ClickStack stores and queries the data in ClickHouse.
27+
28+
Time required: 10–20 minutes
29+
:::
30+
31+
<!-- vale off -->
32+
## What is Odigos? {#what-is-odigos}
33+
<!-- vale on -->
34+
35+
[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.
36+
37+
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:
38+
39+
- **Code-level context** — attributes tied to functions and runtime behavior
40+
- **HTTP traffic** — requests and responses across your services
41+
- **Messaging systems** — payloads and messages from Kafka and similar brokers
42+
- **Errors in detail** — stack traces when things fail
43+
- **Custom instrumentation** — extend coverage where auto-instrumentation stops without requiring code changes or restarts
44+
45+
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.
46+
47+
<!-- vale off -->
48+
## Why Odigos + ClickStack? {#why-odigos-clickstack}
49+
<!-- vale on -->
50+
51+
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; ClickStack provides ClickHouse-backed storage and the HyperDX UI for querying telemetry at scale.
52+
53+
:::tip[Key takeaways]
54+
- **Odigos** auto-instruments any Kubernetes workload without requiring restarts and manages OpenTelemetry pipelines automatically.
55+
- **ClickStack** stores logs, metrics, and traces in ClickHouse and surfaces them in HyperDX.
56+
:::
57+
58+
## Prerequisites {#prerequisites}
59+
60+
- **ClickStack** installed and reachable from your Kubernetes cluster. See [Getting started with open source ClickStack](/use-cases/observability/clickstack/getting-started/oss) or [Getting started with managed ClickStack](/use-cases/observability/clickstack/getting-started/managed).
61+
- Your ClickStack **OTLP HTTP endpoint** (port `4318`) and the authentication value Odigos will pass in the `Authorization` header. With open source ClickStack this is the **API ingestion key** from **Team Settings → API Keys** in the HyperDX UI. With Managed ClickStack this is the **`OTLP_AUTH_TOKEN`** you set when starting your own standalone ClickStack collector.
62+
- A **Kubernetes cluster** (Linux nodes with kernel 4.18 or later for eBPF instrumentation)
63+
- **Helm**, **kubectl**, and cluster credentials to install into `odigos-system` namespace
64+
- An **Odigos Enterprise on-prem token** — contact the [Odigos team](https://odigos.io/) for access
65+
66+
<!-- vale off -->
67+
## Integrate ClickStack with Odigos {#integrate-odigos-clickstack}
68+
<!-- vale on -->
69+
70+
<VerticalStepper headerLevel="h4">
71+
72+
#### Deploy Odigos with Helm {#deploy-odigos}
73+
74+
Odigos Enterprise requires an on-prem license token. Export it in your shell:
75+
76+
```bash
77+
export ODIGOS_ONPREM_TOKEN="<your-enterprise-token>"
78+
```
79+
Alternatively, you can store the token in a Kubernetes Secret named `odigos-pro` before installing. See [Odigos Enterprise installation](https://docs.odigos.io/enterprise/setup/installation).
80+
81+
Add the Odigos Helm repository and install the chart into `odigos-system`:
82+
83+
```bash
84+
helm repo add odigos https://odigos-io.github.io/odigos/
85+
helm repo update
86+
87+
helm upgrade --install odigos odigos/odigos \
88+
--namespace odigos-system \
89+
--create-namespace \
90+
--set onPremToken=$ODIGOS_ONPREM_TOKEN
91+
```
92+
93+
You can pass additional configuration overrides with `--set` flags or a custom values file (`-f`). The chart's default values are in [helm/odigos/values.yaml](https://github.com/odigos-io/odigos/blob/main/helm/odigos/values.yaml) on GitHub.
94+
95+
Verify Odigos pods are running:
96+
97+
```bash
98+
kubectl get pods -n odigos-system
99+
```
100+
101+
#### Add sources in the Odigos UI {#add-sources}
102+
103+
1. Port-forward the Odigos UI service:
104+
105+
```bash
106+
kubectl port-forward svc/ui -n odigos-system 3000:3000
107+
```
108+
109+
2. Open [http://localhost:3000](http://localhost:3000) in your browser.
110+
3. Go to **Sources** and select the namespaces or workloads you want to instrument.
111+
4. Click done at the bottom, once you have marked all workloads for instrumentation.
112+
5. Verify workloads have been instrumented successfully in the sources column.
113+
114+
#### Add ClickStack as a destination in the Odigos UI {#add-destination-ui}
115+
116+
To send telemetry to ClickStack, add an **OTLP HTTP** destination in Odigos. The exact configuration depends on how ClickStack is deployed. With open source ClickStack the OpenTelemetry collector is bundled and the ingestion key is generated for you in the HyperDX UI. With Managed ClickStack you run your own standalone ClickStack collector and choose the authentication token yourself when starting the container.
117+
118+
:::tip[Alternative: write directly to ClickHouse]
119+
If ClickHouse is reachable from your Kubernetes cluster, you can skip the OTLP collector entirely and use Odigos's [native **ClickHouse** destination](#native-clickhouse-destination) instead. This works for both open source and Managed ClickStack.
120+
:::
121+
122+
<Tabs groupId="clickstack-deployment">
123+
124+
<TabItem value="oss-clickstack" label="Open Source ClickStack" default>
125+
126+
With open source ClickStack, for example the all-in-one image, the gateway OpenTelemetry collector is included and the ingestion API key is generated automatically by HyperDX.
127+
128+
1. In the Odigos UI, click **Add Destination** and select **OTLP HTTP**.
129+
2. Set **OTLP HTTP Endpoint** to your ClickStack collector (for example, `http://clickstack.example.com:4318`). See [Ingesting with OpenTelemetry](/use-cases/observability/clickstack/ingesting-data/opentelemetry#sending-data-to-collector-oss) for endpoint details.
130+
3. Copy your API ingestion key from the ClickStack UI under **Team Settings → API Keys**.
131+
4. In **Headers**, add:
132+
- **Key**: `Authorization`
133+
- **Value**: your API ingestion key
134+
5. Enable **Logs**, **Metrics**, and **Traces**.
135+
6. Save the destination.
136+
137+
</TabItem>
138+
139+
<TabItem value="managed-clickstack" label="Managed ClickStack">
140+
141+
Managed ClickStack does not ship a hosted OpenTelemetry collector or surface an ingestion key in the UI. Instead, you run the [ClickStack distribution of the collector in standalone mode](/use-cases/observability/clickstack/ingesting-data/otel-collector#configuring-the-collector) 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.
142+
143+
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:
144+
145+
```shell
146+
export CLICKHOUSE_ENDPOINT=<HTTPS_ENDPOINT>
147+
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
148+
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>
149+
export OTLP_AUTH_TOKEN="a_very_secure_string"
150+
151+
docker run \
152+
-e OTLP_AUTH_TOKEN=${OTLP_AUTH_TOKEN} \
153+
-e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
154+
-e CLICKHOUSE_USER=${CLICKHOUSE_USER} \
155+
-e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
156+
-p 4317:4317 \
157+
-p 4318:4318 \
158+
clickhouse/clickstack-otel-collector:latest
159+
```
160+
161+
For TLS, dedicated ingestion users, and other production recommendations, see [Securing the collector](/use-cases/observability/clickstack/ingesting-data/otel-collector#securing-the-collector).
162+
2. In the Odigos UI, click **Add Destination** and select **OTLP HTTP**.
163+
3. Set **OTLP HTTP Endpoint** to the standalone collector you just started (for example, `http://my-collector.example.com:4318`).
164+
4. In **Headers**, add:
165+
- **Key**: `Authorization`
166+
- **Value**: the `OTLP_AUTH_TOKEN` value you set on the collector
167+
5. Enable **Logs**, **Metrics**, and **Traces**.
168+
6. Save the destination.
169+
170+
:::note[Optional: Kubernetes manifest]
171+
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.
172+
:::
173+
174+
</TabItem>
175+
176+
</Tabs>
177+
178+
#### Verify telemetry in ClickStack {#verify-telemetry}
179+
180+
1. Open the ClickStack UI (HyperDX):
181+
- **Open source ClickStack**: for example, `http://<host>:8080` on the all-in-one image.
182+
- **Managed ClickStack**: open your service in the [ClickHouse Cloud console](https://console.clickhouse.cloud), then click **Launch ClickStack**. See [Navigate to the ClickStack UI](/use-cases/observability/clickstack/getting-started/managed#navigate-to-clickstack-ui-cloud) for details.
183+
2. Check **Logs**, **Metrics**, and **Traces** for data from your instrumented services.
184+
3. Filter traces by `odigos.version` to validate end-to-end export.
185+
186+
If data is missing, check collector logs: `kubectl logs deploy/odigos-gateway -n odigos-system`
187+
188+
</VerticalStepper>
189+
190+
## Advanced configuration {#advanced-configuration}
191+
192+
### HyperDX log normalizer {#hyperdx-log-normalizer}
193+
194+
If you export directly to ClickHouse with Odigos's native **ClickHouse** destination (instead of OTLP HTTP to ClickStack), enable **HyperDX log normalizer** (`HYPERDX_LOG_NORMALIZER: true`). It parses JSON log bodies and normalizes attributes for better querying in the ClickStack UI.
195+
196+
### Native ClickHouse destination {#native-clickhouse-destination}
197+
198+
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).
199+
200+
- **Production schema**: Set `CLICKHOUSE_CREATE_SCHEME` to `false` and apply your own DDL.
201+
- **TLS / auth**: Use `CLICKHOUSE_TLS_ENABLED`, `CLICKHOUSE_USERNAME`, and a Kubernetes Secret for the password.
202+
203+
### Configure destinations with Kubernetes manifests {#destination-manifest}
204+
205+
**OTLP HTTP (ClickStack)**
206+
207+
```yaml
208+
apiVersion: odigos.io/v1alpha1
209+
kind: Destination
210+
metadata:
211+
name: clickstack
212+
namespace: odigos-system
213+
spec:
214+
type: otlphttp
215+
destinationName: otlphttp
216+
signals:
217+
- TRACES
218+
- METRICS
219+
- LOGS
220+
data:
221+
OTLP_HTTP_ENDPOINT: 'http://clickstack.example.com:4318'
222+
# API ingestion key for open source ClickStack, or OTLP_AUTH_TOKEN for Managed ClickStack
223+
OTLP_HTTP_HEADERS: 'Authorization:<YOUR_AUTHORIZATION_VALUE>'
224+
```
225+
226+
**ClickHouse (direct)**
227+
228+
```yaml
229+
apiVersion: odigos.io/v1alpha1
230+
kind: Destination
231+
metadata:
232+
name: clickhouse
233+
namespace: odigos-system
234+
spec:
235+
type: clickhouse
236+
destinationName: clickhouse
237+
signals:
238+
- TRACES
239+
- METRICS
240+
- LOGS
241+
data:
242+
CLICKHOUSE_ENDPOINT: 'http://clickstack.example.com:8123'
243+
CLICKHOUSE_DATABASE_NAME: 'otel'
244+
CLICKHOUSE_CREATE_SCHEME: 'true'
245+
```
246+
247+
Apply the manifest:
248+
249+
```bash
250+
kubectl apply -f destination.yaml
251+
```
252+
253+
<!-- vale off -->
254+
### Odigos VM Agent {#odigos-vm-agent}
255+
<!-- vale on -->
256+
257+
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 ClickStack over OTLP HTTP.
258+
259+
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.
260+
261+
<!-- vale off -->
262+
### Odigos Central {#odigos-central}
263+
<!-- vale on -->
264+
265+
[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.
266+
267+
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.
268+
269+
## Next steps {#next-steps}
270+
271+
- **Explore traces** across instrumented services in ClickStack
272+
- **Build dashboards** for metrics Odigos exports
273+
- **Tune ClickHouse schema and TTL** for your retention and query patterns
274+
275+
## Read more {#read-more}
276+
277+
- [Odigos Enterprise installation](https://docs.odigos.io/enterprise/setup/installation)
278+
- [Odigos ClickHouse destination](https://docs.odigos.io/backends/clickhouse)
279+
- [Odigos VM Agent overview](https://docs.odigos.io/vmagent/overview)
280+
- [Odigos Central overview](https://docs.odigos.io/central/overview)
281+
- [Stop guessing in production: Full fidelity tracing at scale with ClickHouse and Odigos](https://clickhouse.com/blog/odigos-full-fidelity-tracing)
282+
- [Getting started with open source ClickStack](/use-cases/observability/clickstack/getting-started/oss)

‎styles/ClickHouse/Headings.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,7 @@ exceptions:
109109
- NPM
110110
- NodeJS
111111
- NodeJs
112+
- Odigos
112113
- OLAP
113114
- OLTP
114115
- ORC

0 commit comments

Comments
 (0)