Skip to main content
The ClickHouse integration requires CXDOT Collector 1.4.0 or greater. ClickHouse is a column-oriented database for real-time analytics. Use the ClickHouse integration with the CXDOT Collector to collect query, connection, merge, and replication metrics from ClickHouse servers.

Supported telemetry types

The ClickHouse integration supports these telemetry types:

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

Validate

  1. In the Live Telemetry Analyzer, 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, run the following query while the ClickHouse servers process queries:
    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:

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 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 for gRPC. Please refer to 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 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.