ClickStack

​

What is ClickStack?

​

Key capabilities

• Distributed tracing: Filter and inspect spans by service, attributes, and status in the ClickStack UI
• OpenTelemetry ingestion: Receive OTLP traces over HTTP or gRPC via the ClickStack OTEL Collector

​

Prerequisites

1. TrueFoundry account: Register and complete the Gateway Quick Start Guide
2. ClickStack or ClickHouse Cloud: Sign in to ClickStack or ClickHouse Cloud and note your ClickHouse endpoint, user, and password
3. Hosted OTEL collector: A reachable ClickStack OTEL Collector deployment exposing the OTLP HTTP traces endpoint

​

Architecture overview

[TrueFoundry AI Gateway]
        ↓
[ClickStack OTEL Collector :4318 /v1/traces]
        ↓
[ClickHouse Cloud :8443]
        ↓
[ClickStack UI (HyperDX)]

​

Integration steps

1

Get ClickHouse credentials

From ClickStack or ClickHouse Cloud, collect CLICKHOUSE_ENDPOINT (for example https://<clickhouse-endpoint>:8443), CLICKHOUSE_USER (commonly default), and CLICKHOUSE_PASSWORD for the collector.

2

Deploy the ClickStack OTEL Collector

Image: clickhouse/clickstack-otel-collector:latest

Port	Type	Usage
4317	TCP	OTLP gRPC
4318	HTTP	OTLP HTTP traces

docker run -d \
  --name clickstack-otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  -e CLICKHOUSE_ENDPOINT=https://<clickhouse-endpoint>:8443 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=<password> \
  clickhouse/clickstack-otel-collector:latest

Expose port 4318 (or TLS at a reverse proxy) and use this Traces Endpoint in TrueFoundry:

https://<domain>/v1/traces

Replace <domain> with your collector’s public hostname.

3

Test the collector endpoint

Confirm the endpoint is reachable:

POST https://<domain>/v1/traces

Header	Value
Content-Type	application/json

4

Configure OTEL export in TrueFoundry

1. In the TrueFoundry dashboard go to Settings → Organisation → AI Gateway → OTEL Config.
2. Click the edit (pencil) control on the OTEL card.
3. Enable Otel Traces Exporter Configuration.
4. Select HTTP Configuration.
5. Set Endpoint to https://<domain>/v1/traces.
6. Set Encoding to Json.

The OTEL card summary shows your saved Config Type, Traces Endpoint, and Headers before you open the editor:

5

Configure headers and save

In the exporter form, enable Headers and add:

Header	Value
Content-Type	application/json

Click Save to apply the configuration.

6

Verify the integration

1. Send requests through the TrueFoundry AI Gateway.
2. In ClickStack, open Search → Traces, set a recent time range, and filter ServiceName = tfy-llm-gateway.

​

Configuration summary