> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/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 with the
[CXDOT Collector](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector)
to collect query,
connection, merge, and replication metrics from ClickHouse servers.

## Supported telemetry types

The ClickHouse integration supports these telemetry types:

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

## Prerequisites

Meet these requirements before configuring the integration:

* Allow the Collector to connect to each ClickHouse HTTP interface.
* Use 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

The ClickHouse integration is enabled by default. You can configure targets either by
annotating pods in your Kubernetes cluster or by listing static endpoints in your Helm
values. To configure the ClickHouse integration, follow these steps:

1. To collect from ClickHouse pods in Kubernetes, add a CXDOT integration annotation to
   the pod template. The annotation key must end with the container name, and its value
   can reference credentials stored in a Kubernetes Secret in the same namespace. For
   example, add the following annotation to your ClickHouse workload:

   ```yaml theme={null}
   spec:
     template:
       metadata:
         annotations:
           integrations.cxdot.paloaltonetworks.com/clickhouse: |
             schema_version: v1.14
             clickhouse:
               instances:
                 - endpoint: http://${target.host}:${target.port.http}
               username: cxdot
               password: ${k8s_secret:clickhouse-credentials/password}
       spec:
         containers:
           - name: clickhouse
             image: clickhouse/clickhouse-server:26.3
             ports:
               - name: http
                 containerPort: 8123
   ```

   The Collector replaces `${target.host}` with the pod IP address,
   `${target.port.http}` with the container port named `http`, and
   `${k8s_secret:clickhouse-credentials/password}` with the `password` key of the
   `clickhouse-credentials` Secret. To allow the Collector to read the Secret, add the
   pod's namespace to `apiServer.metadataServer.secretAllowlist` in the Helm values for
   your CXDOT Collector.

2. Optional: To collect from ClickHouse servers outside your Kubernetes cluster,
   configure static targets: list their HTTP interface URLs in `instances`. Static
   targets run on the cluster Collector, so provide the password through
   `clusterCollector.extraEnv`. For example:

   ```yaml theme={null}
   clusterCollector:
     extraEnv:
       - name: CLICKHOUSE_PASSWORD
         valueFrom:
           secretKeyRef:
             name: clickhouse-credentials
             key: password

   collection:
     cxdot:
       integrations:
         clickhouse:
           instances:
             - endpoint: http://clickhouse.example.com:8123
           username: default
           password: "${env:CLICKHOUSE_PASSWORD}"
   ```

   A nonempty `instances` list disables annotation discovery for that integration
   instance. The Collector scrapes only the listed targets.

3. Optional: To combine annotated pods and static targets, configure separate instances.
   The unnamed instance discovers pods, and the named instance scrapes the static
   targets:

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

   The `clickhouse/static` key defines a named instance and uses the Secret-backed
   environment variable from the preceding example.

For more information about how the CXDOT Collector discovers targets, see
[autodiscovery](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes.md).

### Validate

1. In the
   [Live Telemetry Analyzer](https://docs-xcor.paloaltonetworks.com/investigate/analyze/telemetry-analyzer.md),
   add the following label filters:

   * Set **Label** to `__name__` and **Value** to
     `cxdot.integration.target.health`.
   * Set **Label** to `cxdot.integration.name` and **Value** to `clickhouse`.

   Group the results by `cxdot.integration.target`, and confirm that the metric
   reports `1` for each target.

2. In
   [Metrics Explorer](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/explorer.md),
   run the following query while the ClickHouse servers process queries:

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

   Confirm that the query returns a value greater than `0` for each target.

## Troubleshoot missing metrics

If expected ClickHouse metrics are missing, confirm that the ClickHouse account can
read every system table listed in the prerequisites. The integration collects metric
groups from separate system tables, so a permissions error can affect only some of
the collected metrics.

## Disable the ClickHouse integration

Deleting every `clickhouse` block restores the default unnamed instance. To remove
custom settings and stop collection, retain a disabled configuration:

```yaml theme={null}
collection:
  cxdot:
    integrations:
      clickhouse:
        enabled: false
```

## Configuration reference

Configure one ClickHouse integration instance with the following settings. In Helm values, place
these settings under `collection.cxdot.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 connections to the configured instances.

* **`password`**
  Type: `string`. Optional.
  ClickHouse password for connections to the configured instances. 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. Default: `[]`.
  ClickHouse 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 the configured 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

- [CXDOT Collector integrations](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector.md)
- [Clickhouse  destination plugin](https://docs-xcor.paloaltonetworks.com/ingest/pipeline/plugins/destination-plugins/clickhouse.md)
- [Use comments to provide context](https://docs-xcor.paloaltonetworks.com/navigate/comments.md)
- [Team and collection home pages](https://docs-xcor.paloaltonetworks.com/administer/collections/home.md)
- [Use notebooks to gather related information](https://docs-xcor.paloaltonetworks.com/navigate/notebooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.