Integrate a MySQL instance-Cloud Monitor(CMS)-阿里云帮助中心

This topic describes how to connect a self-managed MySQL or MariaDB database to Cloud Monitor. The integration component uses the aio-exporter for MySQL (mysqld) to collect metrics for various monitoring scenarios, such as connections, queries per second (QPS), the InnoDB buffer pool, master-slave replication, and slow queries. You can deploy this solution in two environments: Container Service for Kubernetes (ACK) clusters and on Elastic Compute Service (ECS) instances in a virtual private cloud (VPC). After the integration is complete, Cloud Monitor automatically creates MySQL instance entities, built-in dashboards, and alert rules.

Requirements

Before you connect, confirm that the target instance meets the following requirements. Otherwise, data collection may fail or metrics may be missing.

Condition	Requirement
Database version	MySQL 5.6 or later, or MariaDB 10.3 or later. End-to-end validation was performed on MySQL 8.0. The available data collection items depend on the database version (from 5.1 to 8.0). Older versions support fewer items. `perf_schema`-related items require version 5.6 or later. `sys_user_summary` and `innodb_sys_tablespaces` require version 5.7 or later. Group Replication Applier Worker requires version 8.0.
Deployment type	Self-managed MySQL, MariaDB, or Percona. Cloud-hosted managed instances, such as ApsaraDB RDS for MySQL, can also be connected if they meet the account and network requirements. When connecting, set "Cloud Vendor/Deployment Source" to the corresponding cloud provider.
Monitoring account	A dedicated read-only account is required. The account must have `PROCESS`, `REPLICATION CLIENT`, and `SELECT ON .` permissions. Do not use the root account.
Connection method	Connect using the `user:password@tcp(host:port)/` format. TLS is disabled by default. If the instance has `require_secure_transport` enabled to force encrypted connections, this connection method cannot be used.
Network connectivity	The exporter must connect directly to the database port (default: 3306). In an ACK environment, the target MySQL instance must be accessible from the selected cluster network. In an ECS environment that uses a VPC, the vSwitch CIDR block of the managed agent must be able to access the target ECS instance. Add the required outbound IP addresses to the security group and whitelist.
Collection overhead	`global_status`, `global_variables`, `slave_status`, and `innodb_metrics` are enabled by default and have low overhead. Optional items, such as `processlist`, table-level statistics, and `performance_schema`-class items, cause significant overhead on large instances. Enable these items as needed.

Prerequisites

Managed Service for Prometheus is activated.
To integrate the CS environment, the target ACK cluster must be connected to Cloud Monitor 2.0 and running, and the target MySQL service must be accessible within the cluster network.
For ECS (VPC) environments: The target MySQL service is hosted on an ECS instance that 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: Create a monitoring account

Execute the following SQL statement on the target database to create a dedicated monitoring account and grant permissions. The MAX_USER_CONNECTIONS parameter limits the number of connections for the monitoring account to prevent impacts on your business:

CREATE USER 'exporter'@'%' IDENTIFIED BY '<password>' WITH MAX_USER_CONNECTIONS 3;
GRANT PROCESS, REPLICATION CLIENT, SELECT ON *.* TO 'exporter'@'%';
FLUSH PRIVILEGES;

Permission	Purpose
PROCESS	Read the process list and global status
REPLICATION CLIENT	Read the primary/secondary replication status
SELECT	Read metadata from schemas such as information_schema and performance_schema

Step 2: Select an integration environment

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

This method installs the 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 MySQL service must be accessible from the cluster's network. For example, the MySQL service can be a service within the cluster or a service in a VPC that the cluster can access via an internal network address.

ECS (VPC)

You select the ECS instance where the target MySQL 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: The vSwitch CIDR block where the managed agent is located must allow access to the target ECS instance. You must configure security groups and access control lists (ACLs) to grant this access.

Environment	Exporter deployment location	Installing a process on the application server	Monitored object	Network accessibility requirements
CS	A user-specified ACK cluster	No (Deployed within the cluster, does not occupy the business pod's host)	ACK cluster	MySQL is accessible from within the cluster's network
ECS (VPC)	A fully managed data collector deployed by the system based on the VPC	No, no processes are installed on the ECS instance	ECS instance	The vSwitch CIDR block of the managed agent can access the target ECS instance

Step 3: Configure integration

Log on to the Cloud Monitor 2.0 console, select the target workspace, click Integration Center in the navigation pane on the left, and then click MySQL to start the integration.
Select the integration environment (CS or ECS (VPC)), and then select the Monitored Object from the drop-down list.

Configure the integration settings, and then click OK:

Configuration Item	Required	Description
MySQL Service Endpoint	Yes	For a CS environment, enter the in-cluster endpoint, such as `mysql-server.<namespace>`. For an ECS (VPC) environment, enter the internal or public endpoint.
MySQL Service Port	Yes	The default is 3306.
Cloud Vendor / Deployment Source	No	This value is written to the `provider` metric tag and used for entity discovery. Select "Self-hosted" (`self-hosted/mysql`) for self-built deployments, or select the corresponding cloud vendor for cloud-hosted deployments.
Network Connectivity Test	—	Available only for CS environments. It is used to validate the network connectivity between the Exporter and the database.
MySQL Account	Yes	The monitoring account created in Step 1. The default is `exporter`.
MySQL Password	Yes	The password for the monitoring account.
Metric Collection Interval (seconds)	Yes	The default is 15. The value range is 1 to 60.
Additional Collection Items	No	Append collection items in addition to the four default items. You can select multiple items. Items such as `processlist`, table-level statistics, and `performance_schema` classes have high overhead. Enable them as needed.
Custom Tags	No	Additional tags injected into metrics. They help you filter metrics by business dimension.
Use Public Registry Address	No	This is disabled by default to use the image repository over the VPC internal network. Enable this option if the internal image repository is inaccessible.

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

Data usage

Entities

After integration, Cloud Monitor discovers MySQL instances every 3 minutes from the labels of the mysql_up metric and creates middleware entities:

Dimension	Description
Domain	middleware
Entity type	middleware.mysql
Entity filter condition	`.entity with(domain='middleware', type='middleware.mysql')`
Observed object (bound entity)	For CS environments: `acs.ack.cluster`. For ECS (VPC) environments: `acs.ecs.instance`.

Entity fields are populated from collected labels and are independent of the number of installations:

Field	Description
instance_id	The instance identity. It is obtained from the `target_uri` label in the `host:port` format.
provider	The deployment source, such as `self-hosted/mysql` or `alibaba-cloud/rds`.
port	The database port.
region_id	The region.
env_type	The deployment environment type (CS or ECS).
cluster_id	The ID of the cluster to which the instance belongs.

You can retrieve instances using the preceding fields in the Entity Explorer or Middleware Insight application.

Built-in dashboards

Dashboard name	Access point	Description
MySQL Overview (Instance Overview)	The Instance Overview tab on the entity details page.	A UModel dashboard that automatically binds the `target_uri` and `provider` variables based on the instance context.
MySQL Overview	The Grafana dashboard list.	A Grafana dashboard available in both Chinese and English.

Core metrics

The following is a complete list of the 57 metrics for the middleware.metric.mysql entity dataset. You can use these metrics directly in entity details, dashboards, and alerts:

Metric name	Type	Unit	Display name	Description
mysql_up	gauge	-	MySQL Active	Indicates whether the MySQL/MariaDB instance is reachable and data collection is successful. A value of 1 indicates that the instance is active. A value of 0 indicates that the instance is unavailable.
mysql_uptime	gauge	s	Running Time	The number of seconds the MySQL service process has been running since startup.
mysql_qps	counter	count/s	Queries Per Second	The number of queries per second (QPS) for statements executed by clients (Questions). This does not include commands such as COM_PING or COM_STATISTICS.
mysql_queries_s	counter	count/s	Total Queries Per Second	The total number of statements executed per second, including statements within stored programs (Queries).
mysql_threads_connected	gauge	-	Connected Threads	The number of client threads currently connected to the server.
mysql_threads_running	gauge	-	Running Threads	The number of non-idle threads that are currently executing statements.
mysql_slow_queries_s	counter	count/s	Slow Queries Per Second	The rate of slow queries per second that take longer than the `long_query_time` to execute.
mysql_buffer_pool_size	gauge	bytes	InnoDB Buffer Pool Size	The configured size of the InnoDB buffer pool in bytes (`innodb_buffer_pool_size`).
mysql_connection_usage	gauge	%	Connection Usage	The percentage of `max_connections` that is used by the current number of connected threads.
mysql_max_used	gauge	-	Max Used Connections	The peak number of concurrent connections since the last `FLUSH STATUS` command or service restart.
mysql_max_connections	gauge	-	Maximum Connections	The maximum number of concurrent client connections allowed (`max_connections`).
mysql_cached	gauge	-	Cached Threads	The number of idle, reusable threads in the thread cache.
mysql_created_s	counter	count/s	Threads Created Per Second	The rate at which new threads are created to handle connections. A high rate may indicate that the `thread_cache_size` is too small.
mysql_aborted_connects	counter	-	Aborted Connections	The rate of failed connection attempts, such as authentication failures or rejected hosts.
mysql_aborted_clients	counter	-	Aborted Clients	The rate of connections aborted because clients did not close the connection properly.
mysql_connection_errors	counter	-	Connection Errors	The rate of connection errors, aggregated by error type, such as `max_connections`, `accept`, or `internal`.
mysql_top_command_counters	counter	-	Top Command Counters	The execution rate of the top 10 `COM_*` commands, categorized by command type.
mysql_handlers	counter	-	Handler Requests	The rate of the top 10 storage engine handler requests, categorized by handler type, such as `read_next`, `write`, or `update`.
mysql_full_join	counter	-	Full Joins	The rate of joins that perform a full table scan on the first table (`Select_full_join`). This usually indicates a missing index.
mysql_full_range_join	counter	-	Full Range Joins	The rate of joins that use a range search on the reference table (`Select_full_range_join`).
mysql_range	counter	-	Range Queries	The rate of joins that use a range scan on the first table (`Select_range`).
mysql_range_check	counter	-	Range Check Queries	The rate of joins that check key usage after each row (`Select_range_check`). This is generally not good for performance.
mysql_scan	counter	-	Full Table Scans	The rate of queries that perform a full table scan on the first table (`Select_scan`).
mysql_sort_rows	counter	-	Rows Sorted	The rate of rows that are sorted (`Sort_rows`).
mysql_sort_range	counter	-	Range Sorts	The rate of sorts that use a range (`Sort_range`).
mysql_sort_merge_passes	counter	-	Sort Merge Passes	The rate of sort merge passes. A high rate may require you to increase the `sort_buffer_size`.
mysql_sort_scan	counter	-	Scan Sorts	The rate of sorts performed by scanning a table (`Sort_scan`).
mysql_tmp_tables	counter	-	Temporary Tables Created	The rate at which internal temporary tables are created in memory (`Created_tmp_tables`).
mysql_tmp_disk_tables	counter	-	Disk Temporary Tables Created	The rate at which internal temporary tables are created on disk (`Created_tmp_disk_tables`). If the proportion of disk temporary tables to in-memory temporary tables is high, optimization is required.
mysql_tmp_files	counter	-	Temporary Files Created	The rate at which the server creates temporary files (`Created_tmp_files`).
mysql_immediate	counter	-	Immediate Table Locks	The rate at which table locks are granted immediately (`Table_locks_immediate`).
mysql_waited	counter	-	Number of waiting table locks	The rate of table locks that had to be waited for (`Table_locks_waited`). A high rate indicates lock contention.
mysql_received	counter	bytes	Received Traffic	The number of bytes received from all clients per second.
mysql_sent	counter	bytes	Sent Traffic	The number of bytes sent to all clients per second.
mysql_data	gauge	-	Buffer Pool Pages	The number of pages in the InnoDB buffer pool. This metric has dimensions for different page states.
mysql_dirty	gauge	-	Dirty Buffer Pool Pages	The number of dirty pages in the InnoDB buffer pool that are waiting to be flushed to disk.
mysql_innodb_row_operations	counter	count/s	InnoDB Row Operations	The rate of InnoDB row operations, aggregated by operation type (read, insert, update, or delete).
mysql_read	counter	-	Buffer Page Reads	The rate of InnoDB buffer page reads, aggregated by page type.
mysql_written	counter	-	Buffer Page Writes	The rate of InnoDB buffer page writes, aggregated by page type.
mysql_log_waits	counter	-	InnoDB Log Waits	The rate of waits for space in the InnoDB redo log buffer (`Innodb_log_waits`). A high rate may require you to increase the `innodb_log_buffer_size`.
mysql_open_files	gauge	-	Open Files	The number of files currently opened by the server.
mysql_open_files_limit	gauge	-	Open Files Limit	The maximum number of file descriptors that the server is allowed to open (`open_files_limit`).
mysql_opened_files_s	counter	count/s	Files Opened Per Second	The rate at which the server opens files. A persistently high rate may indicate an insufficient table or file cache.
mysql_open_tables	gauge	-	Open Tables	The number of tables currently open in the table cache.
mysql_table_open_cache	gauge	-	Table Open Cache	The configured size of the table open cache (`table_open_cache`).
mysql_opened_tables_s	counter	count/s	Tables Opened Per Second	The rate at which tables are opened. If this rate is high relative to the number of open tables, you may need to increase the `table_open_cache` size.
mysql_cache_hits	counter	-	Table Cache Hits	The rate of hits in the table open cache (the table was already in the cache).
mysql_cache_misses	counter	-	Table Cache Misses	The rate of misses in the table open cache (the table had to be reopened).
mysql_process_states	gauge	-	Process State Distribution	The number of threads in the `PROCESSLIST`, aggregated by thread state.
mysql_user	gauge	-	Connections by User	The number of threads in the `PROCESSLIST`, aggregated by MySQL user.
mysql_cmd	gauge	-	Connections by Command	The number of threads in the `PROCESSLIST`, aggregated by the current command, such as `Sleep` or `Query`.
mysql_io_running	gauge	-	Replica I/O Thread State	Indicates whether the replica I/O thread is running (1/Yes). This applies to replica instances.
mysql_sql_running	gauge	-	Replica SQL Thread State	Indicates whether the replica SQL thread is running (1/Yes). This applies to replica instances.
mysql_seconds_behind_master	gauge	s	Replication Lag	The replication delay in seconds relative to the primary database (`Seconds_Behind_Master`/`Seconds_Behind_Source`).
mysql_relay_log_space	gauge	-	Relay Log Space	The total size in bytes of the relay log on the replica.
mysql_collector_success_duration	gauge	-	Collector Scrape Success	Indicates whether each `mysqld_exporter` collector scrape was successful (1 for success, 0 for failure).
mysql_duration	gauge	s	Collector Scrape Duration	The duration in seconds of the last scrape for each `mysqld_exporter` collector.

In addition to the aggregated MetricSet metrics listed above, the raw metrics collected by the exporter (such as mysql_*, mysql_global_status_*, and mysql_slave_status_*) are written to Prometheus storage. You can query them directly using Prometheus Query Language (PromQL).

Common query examples

# Instance QPS
sum by (target_uri) (rate(mysql_global_status_questions[5m]))

# Connection usage (%)
100 * mysql_global_status_threads_connected / clamp_min(mysql_global_variables_max_connections, 1)

# Slow queries per second
sum by (target_uri) (rate(mysql_global_status_slow_queries[5m]))

# InnoDB buffer pool hit rate (%)
100 * (1 - rate(mysql_global_status_innodb_buffer_pool_reads[5m])
        / clamp_min(rate(mysql_global_status_innodb_buffer_pool_read_requests[5m]), 1))

# Replication lag (seconds)
mysql_slave_status_seconds_behind_master

Alert templates

After integration, the following alert rules are automatically enabled and require no manual configuration. The rules are the same for both CS and ECS (VPC) environments. Alert level P1 corresponds to critical, and P2 corresponds to warning.

Alert name	Level	PromQL expression	Duration	Description
MySQLDown	P1 (critical)	`mysql_up != 1`	5m	Instance is unavailable.
MySQLReplicationNotRunning	P1 (critical)	`mysql_slave_status_slave_io_running == 0 or mysql_slave_status_slave_sql_running == 0`	2m	Replication I/O or SQL thread has stopped.
MySQLReplicationLag	P1 (critical)	`(instance:mysql_slave_lag_seconds > 30) and on(instance) (predict_linear(instance:mysql_slave_lag_seconds[5m], 60 * 2) > 0)`	1m	Replication delay is increasing and has not recovered.
MySQLHeartbeatLag	P1 (critical)	`(instance:mysql_heartbeat_lag_seconds > 30) and on(instance) (predict_linear(instance:mysql_heartbeat_lag_seconds[5m], 60 * 2) > 0)`	1m	Heartbeat lag is increasing and has not recovered.
MySQLNotReady	P2 (warning)	`mysql_global_status_wsrep_ready != 1`	5m	Galera cluster node is not ready.
MySQLOutOfSync	P2 (warning)	`(mysql_global_status_wsrep_local_state != 4 and mysql_global_variables_wsrep_desync == 0)`	5m	Galera cluster node is out of sync.
MySQLDonorFallingBehind	P2 (warning)	`(mysql_global_status_wsrep_local_state == 2 and mysql_global_status_wsrep_local_recv_queue > 100)`	5m	Donor node is falling behind, and the receive queue is backlogged.
MySQLInnoDBLogWaits	P2 (warning)	`rate(mysql_global_status_innodb_log_waits[15m]) > 10`	—	InnoDB log writes are waiting for the disk.

The MySQLNotReady, MySQLOutOfSync, and MySQLDonorFallingBehind alerts depend on Galera (wsrep) related metrics and take effect only on Galera or PXC clusters.

Storage policies

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

Data type	Default storage location	Notes
Metrics	Prometheus instance: RegionShare:{{workspaceName}}:{{regionId}}	Associated with the `middleware.metric.mysql` dataset. Filter by `instance_id='<host>:<port>'`.

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.