ClickHouse

The ClickHouse destination exports logs, metrics, and traces from a Bindplane pipeline to a ClickHouse 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 Types

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.
• 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. A minimal example for auto-creation:

  CREATE USER bindplane IDENTIFIED WITH sha256_password BY '<password>';
  GRANT CREATE DATABASE, CREATE TABLE, ALTER, INSERT, SELECT ON otel.* TO bindplane;

Configuration

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.
Endpoint(s)	Strings	Yes	(empty)	The ClickHouse server host:port address(es) to send data to. Supports multiple endpoints. See ClickHouse network ports.
Username	String	No	(empty)	Username to authenticate with the ClickHouse server. See access rights.
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.
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.
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.

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.

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.

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.

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: "<password>"
    - 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.

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

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: "<password>"
    - name: database
      value: otel

Related Resources

• ClickHouse exporter (clickhouseexporter) — OpenTelemetry Collector Contrib
• ClickHouse GRANT statement
• ClickHouse network ports