> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/destinations/clickhouse.md). # ClickHouse The ClickHouse destination exports logs, metrics, and traces from a Bindplane pipeline to a [ClickHouse](https://clickhouse.com/docs) server over TCP, HTTP, or HTTPS. Data is written to per-signal tables in a target database, and those tables are created automatically if they do not already exist. ### Supported Telemetry | Metrics | Logs | Traces | | ------- | ---- | ------ | | ✓ | ✓ | ✓ | ### Prerequisites You need a reachable ClickHouse server and a user account with enough privileges to write the telemetry. * **A reachable ClickHouse endpoint.** One or more `host:port` pairs the collector can connect to. The native TCP protocol typically listens on port `9000` (`9440` for TLS) and the HTTP protocol on `8123` (`8443` for HTTPS). See [ClickHouse network ports](https://clickhouse.com/docs/en/guides/sre/network-ports). * **A target database and tables.** The destination writes to a database (default `otel`) and to per-signal tables (default `otel_logs`, `otel_metrics`, `otel_traces`). The exporter creates the database and tables on startup if they do not exist. For production you may instead pre-create the schema yourself and grant the user only insert access. * **A user with the right grants.** Provide a ClickHouse user that can insert into the target tables. If you rely on auto-creation, the user also needs DDL privileges (`CREATE DATABASE`, `CREATE TABLE`, and `ALTER` for TTL changes) on the database. Grants are managed with the [`GRANT` statement](https://clickhouse.com/docs/sql-reference/statements/grant). A minimal example for auto-creation: ```sql CREATE USER bindplane IDENTIFIED WITH sha256_password BY ''; GRANT CREATE DATABASE, CREATE TABLE, ALTER, INSERT, SELECT ON otel.* TO bindplane; ``` ### Configuration
Bindplane docs - ClickHouse - image 1
**Connection** | Parameter | Type | Required | Default | Description | | --------------------- | ---------------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Choose Telemetry Type | Telemetry Selector | No | Logs, Metrics, Traces | Which signals this destination exports. Any combination of Logs, Metrics, and Traces. | | Protocol | Enum: tcp, http, https | No | tcp | Protocol used to send data to ClickHouse. See [ClickHouse interfaces](https://clickhouse.com/docs/en/interfaces/overview). | | Endpoint(s) | Strings | Yes | *(empty)* | The ClickHouse server `host:port` address(es) to send data to. Supports multiple endpoints. See [ClickHouse network ports](https://clickhouse.com/docs/en/guides/sre/network-ports). | | Username | String | No | *(empty)* | Username to authenticate with the ClickHouse server. See [access rights](https://clickhouse.com/docs/en/operations/access-rights#user-account-management). | | Password | String | No | *(empty)* | Password to authenticate with the ClickHouse server. Sensitive value. Authentication is only sent when both Username and Password are set. | | Database | String | No | `otel` | Database name to use when interacting with the ClickHouse server. | **Tables** | Parameter | Type | Required | Default | Description | | ------------------ | ------ | -------- | -------------- | ------------------------------------------------------------------------------------------------- | | Logs table name | String | No | `otel_logs` | Table used for log data. Created if it does not already exist. Shown when Logs is selected. | | Metrics table name | String | No | `otel_metrics` | Table used for metric data. Created if it does not already exist. Shown when Metrics is selected. | | Traces table name | String | No | `otel_traces` | Table used for trace data. Created if it does not already exist. Shown when Traces is selected. | **Advanced** | Parameter | Type | Required | Default | Description | | --------------------- | -------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | TTL | String | No | `0` | Data time-to-live for deleting data from ClickHouse, for example `30m`. `0` means no TTL. See [ClickHouse TTL](https://clickhouse.com/docs/en/guides/developer/ttl). | | Timeout | Duration | No | `5s` | Timeout for each attempt to send data to ClickHouse. | | Connection Parameters | Map | No | *(empty)* | Additional connection parameters used as query parameters in the URL, for example `secure: true` to enable TLS or `compress: gzip`. See [Go client connection settings](https://clickhouse.com/docs/en/integrations/go#connection-settings-1). | | Drop Raw Copy | Boolean | No | `true` | When enabled, the raw copy of the log stored in `log.record.original` is dropped before export. | **Retry on Failure** | Parameter | Type | Required | Default | Description | | ----------------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Enable Retry on Failure | Boolean | No | `true` | Attempt to resend telemetry that failed to transmit. | | Initial interval | Integer | No | `5` | Seconds to wait after the first failure before retrying. Shown when Retry on Failure is enabled. | | Max interval | Integer | No | `30` | Upper bound in seconds on backoff. Shown when Retry on Failure is enabled. | | Max elapsed time | Integer | No | `300` | Maximum seconds spent trying to send a batch before giving up, used to avoid a never-ending retry loop. Shown when Retry on Failure is enabled. | **Sending Queue** | Parameter | Type | Required | Default | Description | | ------------------------- | --------- | -------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable Sending Queue | Boolean | No | `true` | Buffer telemetry temporarily before sending to help avoid data loss during a temporary network outage. | | Number of Consumers | Integer | No | `10` | Number of consumers that dequeue batches. Shown when the Sending Queue is enabled. | | Queue Size | Integer | No | `5000` | Maximum number of batches kept in memory before dropping. Shown when the Sending Queue is enabled. | | Enable Persistent Queuing | Boolean | No | `true` | Buffer telemetry to disk before sending to help avoid data loss during network outages or collector restarts. Shown when the Sending Queue is enabled. | | Persistent Queue Storage | Extension | Yes | `file_storage_persistent_queue` | The storage extension used for the persistent queue. Shown when the Sending Queue and Persistent Queuing are enabled. See [persistent queue](https://docs.bindplane.com/configuration/bindplane-otel-collector/persistent-queue). | {% hint style="info" %} **TLS via connection parameters** TLS is configured through Connection Parameters rather than a dedicated field. Add an entry `secure` with value `true` to enable it. Pair it with the `https` protocol (port `8443`) or the native TLS port `9440`. {% endhint %} {% hint style="warning" %} **Metrics tables are split by type** Metrics are grouped by type (sum, gauge, histogram, and so on) and stored in separate tables that append the type to the metrics table name. With the default `otel_metrics`, gauge metrics land in `otel_metrics_gauge`. See the [exporter README](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/clickhouseexporter/README.md). {% endhint %} ### Examples Send logs, metrics, and traces to a single TCP endpoint with authentication, gzip compression, and TLS enabled via connection parameters. The sending queue, persistent queue, and retry on failure are all enabled. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Destination metadata: name: clickhouse spec: type: clickhouse parameters: - name: telemetry_types value: - Logs - Metrics - Traces - name: protocol value: tcp - name: endpoint value: - 127.0.0.1:9000 - name: username value: bindplane - name: password value: "" - name: database value: otel - name: logs_table_name value: otel_logs - name: metrics_table_name value: otel_metrics - name: traces_table_name value: otel_traces - name: connection_params value: compress: gzip secure: "true" - name: retry_on_failure_enabled value: true - name: sending_queue_enabled value: true - name: persistent_queue_enabled value: true ``` ### Configuration Tips * Use the `https` protocol or set `secure: true` in Connection Parameters when sending across an untrusted network. The native TLS port is `9440`; HTTPS is `8443`. * For production, pre-create the database and tables and grant the user insert-only access, rather than relying on auto-creation. This avoids exporter processes racing to create schema and simplifies upgrades. * Keep the persistent queue enabled when the collector runs on a host that may restart. The queue buffers telemetry to disk so data is not lost across restarts or network outages. ### Troubleshooting #### Authentication or permission denied Symptoms: the destination reports authentication failures or errors creating the database or tables. Solutions: 1. Confirm the Username and Password are correct and that both are set. Authentication is only sent when both fields are populated. 2. Grant the user insert access on the target tables, plus `CREATE DATABASE`, `CREATE TABLE`, and `ALTER` if you rely on auto-creation. See the [`GRANT` statement](https://clickhouse.com/docs/sql-reference/statements/grant). #### Collector fails to start or cannot reach ClickHouse Symptoms: the collector exits on startup, or logs connection errors at runtime. Solutions: 1. Verify the endpoint host and port match the chosen protocol (`9000`/`9440` for native TCP, `8123`/`8443` for HTTP). The collector fails to start if it cannot reach ClickHouse on startup; if the server becomes unreachable later it keeps running and reports an error. 2. If TLS is required, set `secure: true` in Connection Parameters or use the `https` protocol. 3. If TTL is configured, ensure the telemetry includes a `Timestamp` field. The collector can fail to start when TTL is set but the data lacks a timestamp. #### Telemetry is delayed or dropped Symptoms: data arrives late or batches are dropped under load. Solutions: 1. Keep Retry on Failure and the Sending Queue enabled so transient failures are retried and buffered rather than dropped. 2. Increase Queue Size or the Number of Consumers if batches are dropped because the in-memory queue is full. ### Standalone Destination ```yaml apiVersion: bindplane.observiq.com/v1 kind: Destination metadata: name: clickhouse spec: type: clickhouse parameters: - name: telemetry_types value: - Logs - Metrics - Traces - name: protocol value: tcp - name: endpoint value: - 127.0.0.1:9000 - name: username value: bindplane - name: password value: "" - name: database value: otel ``` ### Related Resources * [ClickHouse exporter (clickhouseexporter) — OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/clickhouseexporter/README.md) * [ClickHouse GRANT statement](https://clickhouse.com/docs/sql-reference/statements/grant) * [ClickHouse network ports](https://clickhouse.com/docs/en/guides/sre/network-ports) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/integrations/destinations/clickhouse.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.