Clickhouse Exporter
contrib
Maintainers: @hanjm, @Frapschen, @SpencerTorres
Source: opentelemetry-collector-contrib
Supported Telemetry
Overview
This exporter supports sending OpenTelemetry data to ClickHouse.ClickHouse is an open-source, high performance columnar OLAP database management system for real-time analytics using SQL. Throughput can be measured in rows per second or megabytes per second. If the data is placed in the page cache, a query that is not too complex is processed on modern hardware at a speed of approximately 2-10 GB/s of uncompressed data on a single server. If 10 bytes of columns are extracted, the speed is expected to be around 100-200 million rows per second.Note: Always add batch-processor to collector pipeline, as ClickHouse document says:
We recommend inserting data in packets of at least 1000 rows, or no more than a single request per second. When inserting to a MergeTree table from a tab-separated dump, the insertion speed can be from 50 to 200 MB/s.
Visualization Tools
Official ClickHouse Plugin for Grafana
The official ClickHouse Datasource for Grafana contains features that integrate directly with this exporter. You can view associated logs and traces, as well as visualize other queries such as tables and time series graphs. Learn how to configure the OpenTelemetry integration.Altinity’s ClickHouse Plugin for Grafana
If the official plugin doesn’t meet your needs, you can try the Altinity plugin for ClickHouse, which also supports a wide range of features.Logs
- Get log severity count time series.
- Find any log.
- Find log with specific service.
- Find log with specific attribute.
- Find log with body contain string token.
- Find log with body contain string.
- Find log with body regexp match string.
- Find log with body json extract.
Traces
- Find spans with specific attribute.
- Find traces with traceID (using time primary index and TraceID skip index).
- Find spans is error.
- Find slow spans.
Metrics
Metrics data is stored in different clickhouse tables depending on their types. The tables will have a suffix to distinguish which type of metrics data is stored.| Metrics Type | Metrics Table |
|---|---|
| sum | _sum |
| gauge | _gauge |
| histogram | _histogram |
| exponential histogram | _exponential_histogram |
| summary | _summary |
- Find a sum metrics with name
- Find a sum metrics with name, attribute.
Performance Guide
A single ClickHouse instance with 32 CPU cores and 128 GB RAM can handle around 20 TB (20 Billion) logs per day, the data compression ratio is 7 ~ 11, the compressed data store in disk is 1.8 TB ~ 2.85 TB, add more clickhouse node to cluster can increase linearly. The otel-collector withotlp receiver/batch processor/clickhouse tcp exporter can process
around 40k/s logs entry per CPU cores, add more collector node can increase linearly.
Configuration options
The following settings are required:-
endpoint(no default): The ClickHouse server address, support multi host with port, for example:- tcp protocol
tcp://addr1:port,tcp://addr2:portor TLStcp://addr1:port,addr2:port?secure=true - http protocol
http://addr1:port,addr2:portor httpshttps://addr1:port,addr2:port - clickhouse protocol
clickhouse://addr1:port,addr2:portor TLSclickhouse://addr1:port,addr2:port?secure=true
in_orderstrategy (tries endpoints in the order specified). Alternatively, useconnection_open_strategy=round_robin(distributes connections evenly) orconnection_open_strategy=random(randomly selects endpoints) inconnection_params. See connection_open_strategy documentation. - tcp protocol
addr?dial_timeout=5s&compress=lz4. For a full list of options see the ClickHouse driver documentation
Connection options:
username(default = ): The authentication username.password(default = ): The authentication password.ttl(default = 0): The data time-to-live example 30m, 48h. Also, 0 means no ttl.database(default = default): The database name. Overrides the database defined inendpointwhen this setting is not equal todefault.connection_params(default = {}). Extra connection parameters with map format. Query parameters provided inendpointwill be individually overwritten if present in this map. Parameters can be either driver parameters (e.g.,connection_open_strategy,max_open_conns) that control client-side behavior, or ClickHouse session settings (e.g.,max_execution_time) that are passed to the server. See the driver parameters list for recognized driver options; all others are treated as session settings.create_schema(default = true): When set to true, will run DDL to create the database and tables. (See schema management)compress(default = lz4): Controls the compression algorithm. Valid options:none(disabled),zstd,lz4(default),gzip,deflate,br,true(lz4). Ignored ifcompressis set in theendpointorconnection_params.async_insert(default = true): Enables async inserts. Ignored if async inserts are configured in theendpointorconnection_params. Async inserts may still be overridden server-side.tlsAdvanced TLS configuration (See TLS).
clickhouse-go module offers additional configuration. These can be set in the exporter’s endpoint or connection_params config values.
client_info_productMust be inproductName/versionformat with comma separated entries. By default the exporter will append its binary build information. You can use this information to track the origin ofINSERTstatements in thesystem.query_logtable.
logs_table_name(default = otel_logs): The table name for logs.traces_table_name(default = otel_traces): The table name for traces.metrics_tablesgaugename(default = “otel_metrics_gauge”)
sumname(default = “otel_metrics_sum”)
summaryname(default = “otel_metrics_summary”)
histogramname(default = “otel_metrics_histogram”)
exponential_histogramname(default = “otel_metrics_exp_histogram”)
cluster_name(default = ): Optional. If present, will includeON CLUSTER cluster_namewhen creating tables.
table_enginename(default = MergeTree)params(default = )
ENGINE definition when table is created. If not set then ENGINE defaults to MergeTree().
Can be combined with cluster_name to enable replication for fault tolerance.
Processing:
timeout(default = 5s): The timeout for every attempt to send data to the backend.sending_queueenabled(default = true)num_consumers(default = 10): Number of consumers that dequeue batches; ignored ifenabledisfalsequeue_size(default = 1000): Maximum number of batches kept in memory before dropping data.
retry_on_failureenabled(default = true)initial_interval(default = 5s): The Time to wait after the first failure before retrying; ignored ifenabledisfalsemax_interval(default = 30s): The upper bound on backoff; ignored ifenabledisfalsemax_elapsed_time(default = 300s): The maximum amount of time spent trying to send a batch; ignored ifenabledisfalse
TLS
The exporter supports TLS. To enable TLS, you must specify thesecure=true query parameter in the endpoint URL or use the https scheme.
You may also use certificate authentication with the tls setting:
tls options are inherited from OpenTelemetry’s TLS config structure, more options are available than shown in this example.
Schema management
By default, the exporter will create the database and tables under the names defined in the config. This is fine for simple deployments, but for production workloads, it is recommended that you manage your own schema by settingcreate_schema to false in the config.
This prevents each exporter process from racing to create the database and tables, and makes it easier to upgrade the exporter in the future.
In this mode, the only SQL sent to your server will be for INSERT statements.
The default DDL used by the exporter can be found in internal/sqltemplates.
Be sure to customize the indexes, TTL, and partitioning to fit your deployment.
Column names and types must be the same to preserve compatibility with the exporter’s INSERT statements.
As long as the column names/types match the INSERT statement, you can create whatever kind of table you want.
See ClickHouse’s LogHouse as an example of this flexibility.
Upgrading existing tables
Sometimes new columns are added to the exporter in a backwards compatible way. The exporter runs aDESC TABLE command on startup to determine which of these new columns are available on the table schema.
If you already have tables created by a previous version of the exporter, you will need to add these new columns manually.
Here is an example of a command you can use to update your existing table (adjust database and table names as needed):
internal/sqltemplates folder.
The CREATE TABLE statements will always have the latest columns.
In some cases the table changes will not be backwards compatible. Be sure to check the changelog for breaking changes before upgrading your collector.
Optional table upgrades
As mentioned in the previous section, the exporter is able to detect which columns are present on the schema for backwards compatibility. Here are some columns you can add to your table to update the schema:Example Config
This example shows how to configure the exporter to send data to a ClickHouse server. It uses the native protocol without TLS. The exporter will create the database and tables if they don’t exist. The data is stored for 72 hours (3 days).Experimental JSON support
JSON column types can be enabled per-exporter using thejson config option:
clickhouse.json feature gate was used to enable JSON for all
ClickHouse exporter instances. This feature gate is now deprecated. Use the json
config option instead, which allows per-pipeline control.
You may also need to add enable_json_type=1 to your endpoint or connection_params.
DDL has been updated, but feel free to tune the schema as needed.
DDL can be found in the internal/sqltemplates package.
All Map columns have been replaced with JSON.
ClickHouse v25+ is recommended for reliable JSON support.
Contributing
Before contributing, review the contribution guidelines in CONTRIBUTING.md.Integration tests
Integration tests can be run with the following command (includes unit tests):Configuration
Example Configuration
Last generated: 2026-04-13