> ## 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 ClickStack with Telflo

> Build and roll out OpenTelemetry Collector configurations that send telemetry to ClickStack or write it straight into ClickHouse, with Telflo managing the collector fleet

Partner Integration

> [!NOTE]
>
> **TL;DR**
>
> This guide shows you how to send telemetry to ClickStack from OpenTelemetry Collectors managed by Telflo. You'll learn how to:
>
> * Build a collector configuration in Telflo's visual editor or using the CLI
> * Send the telemetry to Open Source or Managed ClickStack, or write it straight into ClickHouse
> * Remotely deploy configurations to a fleet of collectors
> * Confirm the telemetry lands in ClickStack or in your ClickHouse tables
>
> Time required: 15-20 minutes

## What is Telflo?

Telflo is a vendor-neutral control plane for OpenTelemetry Collectors, providing centralized management for collector configuration across a fleet. It makes large fleets manageable with a visual editor, pipeline tests, and remote deployment of configurations. Telflo manages standard upstream OpenTelemetry collector builds, with no Telflo-specific distribution and no proprietary agent, so collectors your teams already run stay on the same build.

Telflo is also accessible outside the browser, through a [command-line interface](https://docs.telflo.com/docs/cli/). Pair that with the [ClickStack MCP server](https://clickhouse.com/docs/clickstack/mcp.md) and the same agent that queries your telemetry can fix the pipeline that produced it.

## Why Telflo + ClickStack?

ClickStack handles ingestion, storage, and analytical queries at high volume. Telflo centrally operates the fleet of OpenTelemetry Collectors that feeds it, across hosts, clusters, and regions.

Telflo provides:

* Centralized management of OpenTelemetry Collectors across hosts, containers, and Kubernetes
* Visual pipeline editing, with controlled rollouts to the whole fleet or a single group
* Changes verified against sample telemetry before they reach production collectors
* Routing the same telemetry to ClickStack and other destinations at the same time
* Fleet visibility: which collectors are online, what each one is running, and which have drifted

> [!TIP]
>
> **Key takeaways**
>
> * **ClickStack ingests, stores, and queries at scale**
> * **Telflo operates the collector fleet that feeds it**

## Prerequisites

* A destination: [Open Source ClickStack](https://clickhouse.com/docs/clickstack/getting-started/oss.md), [Managed ClickStack](https://clickhouse.com/docs/clickstack/getting-started/managed.md), or a self-managed ClickHouse instance
* Telflo account ([create an account at telflo.com](https://telflo.com))
* Somewhere for the collectors to run: a VM or a Kubernetes cluster
* **Open Source ClickStack**: your ClickStack OTLP endpoint (`4318` for HTTP, `4317` for gRPC) and your ingestion API key, found in HyperDX under **Team Settings → API Keys** ([view docs here for reference](https://clickhouse.com/docs/clickstack/ingesting-data/opentelemetry.md#sending-otel-data))
* **Managed ClickStack**: your ClickHouse Cloud service endpoint (port `8443`) and an ingestion user (see [Creating an ingestion user](https://clickhouse.com/docs/clickstack/ingesting-data/collector.md#creating-an-ingestion-user))
* **Self-managed ClickHouse**: your ClickHouse endpoint, a database for the [ClickStack tables](https://clickhouse.com/docs/clickstack/ingesting-data/schemas.md), and a user that can create and write to them (see [Creating an ingestion user](https://clickhouse.com/docs/clickstack/ingesting-data/collector.md#creating-an-ingestion-user-oss))
* Network connectivity from the collectors to your ClickStack or ClickHouse endpoint

## Integrate ClickStack with Telflo

**1. Build a collector configuration**

1. Sign in to Telflo. On the **Configurations** list, click **New Configuration**, then **Blank configuration**.
2. In **Name Your Configuration**, enter a name and click **Create**.
3. Add receivers: drag one from the palette onto the canvas for each kind of telemetry you collect.
4. Add processors: **Memory Limiter** and **Batch**, plus any others you need to shape data before it leaves the collector. See the [full list of processors Telflo supports](https://docs.telflo.com/docs/build/components#processors).

**2. Add the exporter**

All three paths use the same editor, the same publish step, and the same fleet; only the exporter differs. Pick the tab for your deployment: Open Source ClickStack takes OTLP with an ingestion key; Managed ClickStack and self-managed ClickHouse take direct writes to the ClickStack tables.

**Open Source ClickStack**

1. Drag the **OTLP/HTTP** exporter onto the canvas.
2. Set **Endpoint** to your ClickStack OTLP HTTP endpoint, for example `http://clickstack.example.com:4318`.
3. Under **HTTP Headers**, click **Add header**, then enter `authorization` as the **Header name** and `${env:CLICKSTACK_INGESTION_KEY}` as the **Header value**. Telflo asks for the value when you install the collectors, so the key is never stored in the configuration.

For gRPC, use the **OTLP** exporter on port `4317` with the same header under **gRPC Metadata Headers**.

**Managed ClickStack**

Managed ClickStack does not ship a gateway collector, so there is no hosted OTLP endpoint to send telemetry to. The collector you configure here becomes that [gateway](https://clickhouse.com/docs/clickstack/ingesting-data/collector.md#collector-roles): give it an **OTLP** receiver alongside the ClickHouse exporter, and it writes to your ClickHouse Cloud service. Your SDKs and agent collectors then send OTLP to it on `4318` (HTTP) or `4317` (gRPC).

1. Drag the **ClickHouse** exporter onto the canvas.
2. Fill in **Endpoint** with your ClickHouse Cloud service endpoint (port `8443`), set **Database** to `default`, and set **Username** to your ingestion user.
3. Set **Password** to `${env:CLICKHOUSE_PASSWORD}`. Telflo asks for the value when you install the collectors, so the credential is never stored in the configuration.
4. Under **Schema & Tables**: if the [ClickStack tables](https://clickhouse.com/docs/clickstack/ingesting-data/schemas.md) don't exist yet, leave **Create Schema on Startup** on and the exporter creates them. Turn it off once they exist.

Keep **Batch** upstream of the exporter: ClickHouse performs best with batched inserts. If you already run a [ClickStack collector](https://clickhouse.com/docs/clickstack/ingesting-data/collector.md#configuring-the-collector) as your OTLP gateway, you can instead follow the Open Source ClickStack steps, with the [`OTLP_AUTH_TOKEN`](https://clickhouse.com/docs/clickstack/ingesting-data/collector#securing-the-collector) you set on that collector as the header value.

**Self-managed ClickHouse**

The collector you configure here acts as your [gateway](https://clickhouse.com/docs/clickstack/ingesting-data/collector.md#collector-roles): give it an **OTLP** receiver alongside the ClickHouse exporter. Your SDKs and agent collectors send OTLP to it, and it writes to ClickHouse.

1. Drag the **ClickHouse** exporter onto the canvas.
2. Fill in **Endpoint** (for example `https://clickhouse.example.com:8443`), **Database**, and **Username**, pointing **Database** at the database the ClickStack tables live in.
3. Set **Password** to `${env:CLICKHOUSE_PASSWORD}`. Telflo asks for the value when you install the collectors, so the credential is never stored in the configuration.
4. Under **Schema & Tables**: if the ClickStack tables don't exist yet, leave **Create Schema on Startup** on and the exporter creates them. Turn it off once they exist.

Keep **Batch** upstream of the exporter: ClickHouse performs best with batched inserts. If you already run a [ClickStack collector](https://clickhouse.com/docs/clickstack/ingesting-data/collector.md#configuring-the-collector) as your OTLP gateway, you can instead follow the Open Source ClickStack steps, with the [`OTLP_AUTH_TOKEN`](https://clickhouse.com/docs/clickstack/ingesting-data/collector#securing-the-collector) you set on that collector as the header value.

Draw edges from the receivers through the processors to the exporter, one pipeline per signal. The status row reports **config valid** or the number of errors to fix, and the **YAML** tab shows the generated configuration.

![A collector pipeline in the Telflo editor with the ClickHouse exporter configured](https://mintcdn.com/private-7c7dfe99/5NhXl45F-rkC2yU0/images/clickstack/telflo/telflo-configuration.webp?fit=max\&auto=format\&n=5NhXl45F-rkC2yU0\&q=85\&s=4b8c285f2ceaef0b8d68dfeb998fe899)

Before you roll anything out, you can run sample telemetry through the configuration and check what comes out the other end. See [testing in Telflo](https://docs.telflo.com/docs/testing/overview). Alternatively, you can describe what you're trying to do and the Telflo AI assistant, opened with the **AI** button in the toolbar, builds, validates, and tests the configuration for you. Your own agent can do the same through the [Telflo CLI](https://docs.telflo.com/docs/cli/).

**3. Publish a version**

Click **Publish** in the toolbar. Published versions are read-only; to keep iterating, click **Create New Version**.

**4. Create a fleet and roll out**

1. Go to **Fleet**, click **New Fleet**, and choose where your collectors run, on VMs or in Kubernetes. Enter a **Name** and click **Create fleet**.
2. On the fleet's **Deploy Groups** tab, click **Assign** on the **Default** group and choose your published configuration and version.
3. Click **Install** on the group and enter a value for each environment variable your configuration references; Telflo adds them to the install command. Run that command where the collectors should run, [following Telflo's installation instructions](https://docs.telflo.com/docs/fleet-management/install-collectors). It carries the fleet's install token along with your value, so treat it as sensitive.
4. On the **Collectors** tab, collectors report **Pending pickup**, then **Applying**, then **In sync**.

To roll out a change, publish a new version and assign it to the group; to roll back, assign a previously deployed version.

![A Telflo fleet with every collector in sync after a rollout](https://mintcdn.com/private-7c7dfe99/5NhXl45F-rkC2yU0/images/clickstack/telflo/telflo-fleet.webp?fit=max\&auto=format\&n=5NhXl45F-rkC2yU0\&q=85\&s=fc39b525dff977bd4f637f2b5efb3f78)

**5. Verify telemetry**

Open HyperDX and search for one of your services in the **Search** view; use **Chart Explorer** for metrics. With Managed ClickStack, open your service in the ClickHouse Cloud console and click **Launch ClickStack**. With self-managed ClickHouse, query the [ClickStack tables](https://clickhouse.com/docs/clickstack/ingesting-data/schemas.md) directly, for example `SELECT ServiceName, count() FROM otel_logs GROUP BY ServiceName`.

## Advanced configuration

### Fan-out routing

The same telemetry can go to ClickStack for long-term storage, to another platform during a migration, and to a SIEM for security analysis at once. Add the exporters on the canvas and connect them to the pipelines that should feed them, or start from a prebuilt pipeline in [Telflo's flow library](https://telflo.com/flows).

### Compression and performance

* **OTLP/HTTP and OTLP exporters**: keep **Compression** at gzip.
* **ClickHouse exporter**: keep **Async Insert** on, leave **Compression** at lz4, and add a **Batch** processor upstream. See [Optimizing inserts](https://clickhouse.com/docs/clickstack/ingesting-data/collector.md#optimizing-inserts).

## Next steps

* **Build dashboards**: create visualizations in HyperDX for logs, metrics, and traces
* **Set up alerts**: configure alerts in ClickStack for critical conditions
* **Refine with the AI assistant**: ask it to adjust a pipeline or propose tests
* **Coming from another vendor**: [flows](https://telflo.com/flows) cover the cutover, replacing the agents already on your fleet and dual-shipping to both backends while you compare them

## Read more

* [Telflo documentation](https://docs.telflo.com/docs)
* [Quickstart: from empty canvas to a deployed collector](https://docs.telflo.com/docs/getting-started/quickstart)
* [Testing collector configurations](https://docs.telflo.com/docs/testing/overview)
* [Fleet management in Telflo](https://docs.telflo.com/docs/fleet-management/overview)
* [Installing collectors](https://docs.telflo.com/docs/fleet-management/install-collectors)
* [Ingesting with OpenTelemetry](https://clickhouse.com/docs/clickstack/ingesting-data/opentelemetry.md)
* [ClickStack table schemas](https://clickhouse.com/docs/clickstack/ingesting-data/schemas.md)