Integrate a ClickHouse instance

Requirements

Before you start the integration, make sure that the target instance meets the following requirements. Otherwise, no data may be collected or some metrics may be missing.

Prerequisites

• Managed Service for Prometheus is activated.

• For CS environments: The target ACK cluster is connected to Cloud Monitor 2.0 and is running. The target ClickHouse service is accessible from the cluster network.

• For ECS (VPC) environments: The target ECS instance that hosts ClickHouse is accessible from the vSwitch CIDR block of the managed agent.

Billing

• Billing is based solely on the volume of metric data generated in Billing overview.

Integration methods

Step 1: Prepare a monitoring account (if needed)

If access authentication is enabled for ClickHouse, create a monitoring account with read permissions for the system database. You can skip this step if authentication is not enabled. In the form, keep the username as default and leave the password empty.

Use a dedicated read-only account instead of a superuser. The monitoring account must have read permissions for at least the following:

• system.metrics

• system.asynchronous_metrics

• system.events

• system.parts

Step 2: Select an integration environment

This plugin supports two integration environments: CS and ECS (VPC). These environments work differently. Select the environment based on where your ClickHouse service is deployed:

CS

• Installs an exporter on a specified ACK cluster and uses the existing data collector in the cluster to collect metrics.

• The monitored object is the ACK cluster.

• Network requirements: The target ClickHouse service must be accessible from the cluster network, such as a service within the cluster or a private IP address in a VPC that the cluster can access.

ECS (VPC)

• You select the ECS instance where the target ClickHouse service is deployed. The system then deploys a fully managed data collector based on the VPC information of that ECS instance.

• No processes are installed on the ECS instance.

• The monitored object is the ECS instance.

• Network requirements: You must configure security group rules and ACLs to allow the vSwitch CIDR block of the managed agent to access the target ECS instance.

Step 3: Configure the integration

1. Log on to the Cloud Monitor console. Select the target workspace. In the navigation pane on the left, click Integration Center, and then click ClickHouse.

2. Select an integration environment (CS or ECS (VPC)) and select a Monitored Object from the drop-down list.

3. Configure the integration and click OK.

   Configuration item	Required	Description
   ClickHouse service endpoint	Yes	For a CS environment, enter the in-cluster endpoint. For an ECS (VPC) environment, enter the private or public endpoint (HTTP interface).
   ClickHouse service port	Yes	Default: 8123 (HTTP).
   Cloud vendor / Deployment source	No	This value is written to the provider label of the metric and used for entity discovery. For a self-managed deployment, select 'Self-managed' (self-hosted/clickhouse).
   ClickHouse username	No	Default: default. The account must have read permissions for the `system` database.
   ClickHouse password	No	Can be left empty if access authentication is not enabled.
   Metric collection interval (seconds)	Yes	Default: 15. Value range: 1–60.
   Custom tags	No	Extra labels to be added to metrics.
   Use public image repository	No	Image repository access does not use the VPC Network by default. Enable this option if you are unable to access the internal repository.

4. After the integration is successful, you can view the integrated entities and their observable data in Entity Explorer.

Data usage

Entities

After integration, Cloud Monitor periodically discovers ClickHouse instances from the labels of metrics such as clickhouse_up and generates middleware entities:

Entity fields are derived from collected labels and are not related to the number of installations:

You can search for instances by these fields in the Entity Explorer or Middleware Insight applications.

Built-in dashboards

Core metrics

The following is a complete list of metrics for the middleware.metric.clickhouse entity dataset. These metrics are available for direct use in entity details, dashboards, and alerts:

Example queries

# Liveness
clickhouse_up

# Query rate
rate(clickhouse_query[5m])

# Failed query rate
rate(clickhouse_failed_query[5m])

# Memory usage
clickhouse_memory_tracking

Alert templates

This integration component does not have built-in alert rules. You can configure alerts based on the preceding metrics in the Alert Center. For example, you can set an alert for scenarios where the clickhouse_up liveness metric is not equal to 1, or when the number of connections or the message accumulation exceeds a threshold.

Storage policies

After you integrate ClickHouse, Cloud Monitor creates a corresponding storage instance to store observable data.

Manage or remove the integration

To modify or cancel the integration, go to the Integration Management page of Integration Center, find the corresponding integration policy, and then click Edit or Delete. When you delete the integration policy, the Exporter and the collection configuration are removed together. Historical metrics that have already been written are retained based on the lifecycle policy of the storage.