> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

> ClickHouse query, connection, merge, and replication metrics.

The ClickHouse integration requires CXDOT Collector 1.4.0 or greater.

[ClickHouse](https://clickhouse.com/) is a column-oriented database for real-time
analytics. Use the ClickHouse integration to collect query, connection, merge, and
replication metrics from ClickHouse servers running in your environment.

The ClickHouse integration supports ClickHouse 26.3 or greater.

## Supported telemetry types

The ClickHouse integration supports these telemetry types:

| Type    | Supported |
| ------- | --------- |
| Logs    | No        |
| Metrics | Yes       |
| Traces  | No        |
| Events  | No        |

## Prerequisites

The ClickHouse integration has the following prerequisites:

* A ClickHouse HTTP interface that the Chronosphere XDOT Collector can reach.
* A ClickHouse account that can run `SELECT 1` and read the `system.metrics`,
  `system.events`, `system.asynchronous_metrics`, `system.parts`,
  `system.replicas`, and `system.dictionaries` tables.

## Configure

To configure the ClickHouse integration, follow these steps:

1. For discovered ClickHouse targets, provide the HTTP endpoint and credentials
   through autodiscovery annotations.

   For more information, see
   [autodiscovery](https://docs.chronosphere.io/ingest/cxdot-collector/autodiscovery).

2. Optional: Manually configure ClickHouse servers as an alternative to
   autodiscovery. List each HTTP interface URL under `instances`, and provide the
   password through your deployment's secret management. For example, the following
   Helm values reference the `CLICKHOUSE_PASSWORD` environment variable:

   ```yaml theme={null}
   config:
     integrations:
       clickhouse:
         instances:
           - endpoint: http://clickhouse.example.com:8123
         username: default
         password: "${env:CLICKHOUSE_PASSWORD}"
   ```

### Validate

To validate the ClickHouse integration, follow these steps:

1. In Live Telemetry Analyzer, filter for
   `cxdot.integration.name=clickhouse`. Confirm that the ClickHouse metric names
   appear.

2. In Metrics Explorer, run the following query while the ClickHouse servers
   process queries:

   ```text theme={null}
   sum by ("server.address", "server.port") (rate({"clickhouse.query.count"}[$__rate_interval]))
   ```

   Confirm that the query returns the expected time series for each target.

### Troubleshooting

* Some expected ClickHouse metrics are missing: Confirm that the ClickHouse
  account can read every system table listed in the prerequisites. The
  integration collects different metric groups from different system tables,
  so a permissions error can affect only part of the collected data.

For more information about diagnosing a failing integration, see
[Troubleshooting](https://docs.chronosphere.io/ingest/cxdot-collector/troubleshooting).

## Configuration reference

Configure one ClickHouse integration instance with the following settings. In Helm values, place
these settings under `config.integrations.clickhouse`. In a Collector configuration file, place
them under `cxdot.integrations.clickhouse`.

### Optional settings

* **`enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this ClickHouse integration instance. If true, the Collector runs the
  instance. If false, the Collector doesn't run it.

* **`username`**
  Type: `string`. Optional. Default: `default`.
  ClickHouse user name for static instance connections.

* **`password`**
  Type: `string`. Optional.
  ClickHouse password for static instance connections. The Collector masks this sensitive value
  in diagnostic output, logs, and errors.

* **`database`**
  Type: `string`. Optional. Default: `default`.
  Database to attach the connection to.

* **`collection_interval`**
  Type: `duration`. Optional. Default: `15s`.
  How often the Collector collects metrics from each ClickHouse target.

* **`timeout`**
  Type: `duration`. Optional. Default: `15s`.
  Maximum time allowed to collect metrics from one ClickHouse instance. The value must not
  exceed `collection_interval`.

* **`instances`**
  Type: `array of object`. Optional.
  Static ClickHouse instances. A nonempty list disables automatic discovery for this integration
  instance, and the Collector collects metrics from only the listed instances. Specify each
  `endpoint` as the full URL of the ClickHouse HTTP interface, such as
  `http://clickhouse.default.svc:8123`. Use an HTTPS URL and the `tls` settings for a connection
  that uses TLS.

* **`instances[].endpoint`**
  Type: `string`. Required.
  URL of the instance's HTTP interface.

* **`tls`**
  Type: `object`. Optional.
  Transport layer security (TLS) settings for static HTTPS instances. Certificate verification
  is enabled unless `insecure_skip_verify` is true. These settings don't apply to HTTP instances
  or targets configured through discovery annotations.

* **`tls.ca_file`**
  Type: `string`. Optional.
  Path to the CA cert. For a client this verifies the server certificate. For a server this
  verifies client certificates. If empty uses system root CA. (optional)

* **`tls.ca_pem`**
  Type: `string`. Optional.
  In memory PEM encoded cert. (optional)

* **`tls.cert_file`**
  Type: `string`. Optional.
  Path to the TLS cert to use for TLS required connections. (optional)

* **`tls.cert_pem`**
  Type: `string`. Optional.
  In memory PEM encoded TLS cert to use for TLS required connections. (optional)

* **`tls.cipher_suites`**
  Type: `array of string`. Optional.
  CipherSuites is a list of TLS cipher suites that the TLS transport can use. If left blank, a
  safe default list is used. See
  [https://go.dev/src/crypto/tls/cipher\_suites.go](https://go.dev/src/crypto/tls/cipher_suites.go)
  for a list of supported cipher suites.

* **`tls.curve_preferences`**
  Type: `array of string`. Optional.
  contains the elliptic curves that will be used in an ECDHE handshake, in preference order
  Defaults to empty list and "crypto/tls" defaults are used, internally.

* **`tls.include_system_ca_certs_pool`**
  Type: `boolean`. Optional.
  If true, load system CA certificates pool in addition to the certificates configured in this
  struct.

* **`tls.insecure`**
  Type: `boolean`. Optional.
  In gRPC and HTTP when set to true, this is used to disable the client transport security. See
  [https://godoc.org/google.golang.org/grpc#WithInsecure](https://godoc.org/google.golang.org/grpc#WithInsecure)
  for gRPC. Please refer to
  [https://godoc.org/crypto/tls#Config](https://godoc.org/crypto/tls#Config) for more
  information. (optional, default false)

* **`tls.insecure_skip_verify`**
  Type: `boolean`. Optional.
  InsecureSkipVerify will enable TLS but not verify the certificate.

* **`tls.key_file`**
  Type: `string`. Optional.
  Path to the TLS key to use for TLS required connections. (optional)

* **`tls.key_pem`**
  Type: `string`. Optional.
  In memory PEM encoded TLS key to use for TLS required connections. (optional)

* **`tls.max_version`**
  Type: `string`. Optional.
  MaxVersion sets the maximum TLS version that is acceptable. If not set, refer to crypto/tls
  for defaults. (optional)

* **`tls.min_version`**
  Type: `string`. Optional.
  MinVersion sets the minimum TLS version that is acceptable. If not set, TLS 1.2 will be used.
  (optional)

* **`tls.reload_interval`**
  Type: `duration`. Optional.
  ReloadInterval specifies the duration after which the certificate will be reloaded If not set,
  it will never be reloaded (optional)

* **`tls.server_name_override`**
  Type: `string`. Optional.
  ServerName requested by client for virtual hosting. This sets the ServerName in the TLSConfig.
  Please refer to [https://godoc.org/crypto/tls#Config](https://godoc.org/crypto/tls#Config) for
  more information. (optional)

* **`tls.tpm`**
  Type: `object`. Optional.
  Trusted platform module configuration

* **`tls.tpm.auth`**
  Type: `string`. Optional.
  Authorization value for the trusted platform module key.

* **`tls.tpm.enabled`**
  Type: `boolean`. Optional.
  Whether to use a trusted platform module for the TLS private key. If true, the Collector loads
  the key from the configured device or socket. If false, the Collector uses the configured key
  file or in-memory key.

* **`tls.tpm.owner_auth`**
  Type: `string`. Optional.
  Owner authorization value for the trusted platform module.

* **`tls.tpm.path`**
  Type: `string`. Optional.
  The path to the TPM device or Unix domain socket. For instance /dev/tpm0 or /dev/tpmrm0.


## Related topics

- [Clickhouse  destination plugin](/ingest/pipeline/plugins/destination-plugins/clickhouse.md)
- [Send telemetry data with destination plugins](/ingest/pipeline/plugins/destination-plugins.md)
- [Telemetry Pipeline release notes](/ingest/pipeline/v2/release-notes.md)
- [Use comments to provide context](/navigate/comments.md)
- [Use notebooks to gather related information](/navigate/notebooks.md)