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

> Use Telflo to manage OpenTelemetry Collectors that send telemetry to fully managed or self-managed ClickHouse Observability

Partner Integration

> [!NOTE]
>
> **TL;DR**
>
> This guide shows you how to send telemetry to ClickHouse Observability 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 telemetry to fully managed or self-managed ClickHouse Observability
> * Remotely deploy configurations to a fleet of collectors
> * Confirm the telemetry is available in ClickHouse Observability
>
> 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/observability/mcp.md) and the same agent that queries your telemetry can fix the pipeline that produced it.

## Why Telflo + ClickHouse Observability?

Fully managed ClickHouse Observability handles ingestion, schemas, storage, and scaling. With self-managed ClickHouse Observability, you control ingestion and database configuration while ClickHouse Cloud manages the underlying infrastructure. Telflo manages the OpenTelemetry Collectors that send telemetry from your hosts, clusters, and regions to either deployment.

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 ClickHouse Observability 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**
>
> * **ClickHouse Observability provides the storage and investigation experience**
> * **Telflo operates the collector fleet that feeds it**

## Prerequisites

* A [fully managed ClickHouse Observability service](https://clickhouse.com/docs/clickstack/observability/getting-started.md) or a [self-managed deployment](https://clickhouse.com/docs/clickstack/self-configured/getting-started/managed.md)
* A Telflo account ([create an account at telflo.com](https://telflo.com))
* Somewhere for the collectors to run: a VM or a Kubernetes cluster
* **Fully managed**: your OTLP HTTP endpoint and ingestion API key from **Team Settings → Data → Managed Telemetry**
* **Self-managed**: your ClickHouse Cloud service endpoint (port `8443`) and an [ingestion user](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#creating-an-ingestion-user-self-configured), or an existing standalone collector endpoint and its `OTLP_AUTH_TOKEN`
* Network connectivity from the Telflo-managed collectors to your destination endpoint

## Integrate ClickHouse Observability 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**

Choose the exporter for your deployment. Fully managed ClickHouse Observability accepts telemetry through its managed OTLP endpoint. For self-managed deployments, you can write directly to ClickHouse or send OTLP to a collector you already run.

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> Use the managed OTLP endpoint. ClickHouse handles ingestion, schemas, storage, and scaling; the collectors managed by Telflo collect and forward telemetry from your environment.
>
> 1. Drag the **OTLP/HTTP** exporter onto the canvas.
> 2. Set **Endpoint** to your managed OTLP HTTP endpoint, including port `4318`, for example `https://<service-id>.otel.<region>.aws.clickhouse.com:4318`.
> 3. Under **HTTP Headers**, click **Add header**, then enter `Authorization` as the **Header name** and `Bearer ${env:CLICKSTACK_INGESTION_KEY}` as the **Header value**. Telflo asks for the environment variable value when you install the collectors. Supply your ingestion API key as `CLICKSTACK_INGESTION_KEY`, without the `Bearer` prefix.
>
> Use the OTLP exporter, not the direct ClickHouse exporter, for fully managed deployments.

> [tab] Self-managed
>
> Self-managed ClickHouse Observability requires you to manage ingestion. Direct writes with the ClickHouse exporter apply only to self-managed deployments. The collector you configure here acts as an [ingestion gateway](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#collector-roles-self-configured): 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 configuration references an environment variable rather than containing the password.
> 4. Under **Schema & Tables**: if the [telemetry tables](https://clickhouse.com/docs/clickstack/self-configured/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 [standalone OpenTelemetry collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#configuring-the-collector-self-configured), use an **OTLP/HTTP** exporter instead. Set **Endpoint** to that collector's OTLP HTTP address (port `4318`) and add an `Authorization` header with `${env:OTLP_AUTH_TOKEN}` as its value. Supply the [authentication token configured on your collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#securing-the-collector-self-configured) when installing the Telflo-managed collectors. Do not add a `Bearer` prefix to this token.
>
> ![A self-managed 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)

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.

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 group you want to deploy to and choose your published configuration and version. Start with a small group to verify ingestion before rolling out to the rest of the fleet.
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 ClickHouse Observability for your service in the ClickHouse Cloud console. Search for one of your services in the **Search** view; use **Chart Explorer** for metrics. Check that the expected logs, traces, and metrics have arrived before rolling the configuration out to the rest of your fleet.

## Advanced configuration

### Fan-out routing

The same telemetry can go to ClickHouse Observability 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 (self-managed only)**: keep **Async Insert** on, leave **Compression** at lz4, and add a **Batch** processor upstream. See [Optimizing inserts](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#optimizing-inserts-self-configured).

## Next steps

* **Build dashboards**: create visualizations in ClickHouse Observability for logs, metrics, and traces
* **Set up alerts**: configure alerts in ClickHouse Observability for critical conditions
* **Refine with the Telflo 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/observability/ingesting-data/opentelemetry.md)
* [Self-managed table schemas](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/schemas.md)