MySQL New

信息

MySQL New 使用 SmartAgent + Integration Agent 采集 MySQL 指标及 DBM 数据，可进一步分析 Query 性能、执行计划、活动会话以及数据库与应用服务的关联。

快速上手

安装 SmartAgent 10.3.0 或更高版本，并启用 Integration Agent。
在 MySQL 中创建监控用户、完成基础授权，并启用 performance_schema。
如需采集执行计划，在共享监控库和需要监控的业务库中创建 explain_statement 存储过程。
编辑 ${APM_HOME}/integration/conf/integration.d/mysql.d/conf.yaml，填写连接信息并将 dbm 设置为 true。
运行自检命令确认权限与性能表配置正常，然后进入 基础设施 → 数据库 查看实例及 Query 数据。

注意

此页面介绍新的 Integration Agent 接入方式。现有 MySQL Legacy 使用 SmartGate，部署与配置流程不同，请勿混用。

1. 支持范围

数据库支持版本：

MySQL 5.6/5.7/8.0/8.4/9.7

注：其他数据库版本理论上支持，需要自行验证

支持系统架构：

Linux x86_64（amd64），需glibc ≥2.17；已验证版本：CentOS 7、CentOS 8、CentOS 8.5、Ubuntu 21.10

注：其他系统版本理论上支持，需要自行验证

探针支持版本：

SmartAgent 10.3.0+

2. 部署

安装 SmartAgent 探针，并开启 integration-agent

3. MySQL 端配置：用户与权限

3.1 创建 bonree 用户

bonree：创建的用于插件探针访问数据库的用户；<UNIQUEPASSWORD> ：设置的数据库访问密码。
如需限制哪些 host 段可以用bonree用户访问，可类似这样设置：bonree@'10.0.0.%' 或 bonree@'localhost'。

CREATE USER 'bonree'@'%' IDENTIFIED BY '<UNIQUEPASSWORD>';

检查是否可以访问：

mysql -u bonree --password='<UNIQUEPASSWORD>' -e "SHOW STATUS" | grep Uptime
# 看到 Uptime_since_flush_status 行即可

3.2 基础授权

-- MySQL 8.0+
GRANT REPLICATION CLIENT ON *.* TO 'bonree'@'%';
ALTER USER 'bonree'@'%' WITH MAX_USER_CONNECTIONS 5;

-- MySQL 5.6 / 5.7
-- GRANT REPLICATION CLIENT ON *.* TO 'bonree'@'%' WITH MAX_USER_CONNECTIONS 5;

GRANT PROCESS ON *.* TO 'bonree'@'%';
GRANT SELECT ON performance_schema.* TO 'bonree'@'%';

-- 索引指标（QUERY_INDEX_SIZE）需要：
GRANT SELECT ON mysql.innodb_index_stats TO 'bonree'@'%';

权限	作用	触发它的 check 逻辑
`REPLICATION CLIENT`	允许账号查询主从复制相关状态，读 `SHOW REPLICA STATUS / SHOW BINARY LOGS`	`_collect_replication_metrics`、`_get_binary_log_stats`
`PROCESS`	允许查看数据库所有正在运行的线程 / 会话，监控慢查询、活跃连接、阻塞事务、长 SQL，看其它连接的 processlist	`MySQLActivity`、`_get_replicas_connected_count`
`SELECT on performance_schema.*`	性能指标核心库，存储等待事件、语句耗时、锁、IO、连接性能数据，采集语句指标 / 样本 / 活动 / 元数据	全部 DBM Job
`SELECT on mysql.innodb_index_stats`	InnoDB 索引统计信息表，记录每个索引的行数、页数量、采样统计值，用于计算索引基数、优化 SQL 执行计划，比如获取InnoDB 索引大小	`MySqlIndexMetrics.QUERY_INDEX_SIZE`

3.3 DBM 执行计划采集配置：EXPLAIN 存储过程

创建explain_statement存储过程，以便收集执行计划，需要：

共享监控 schema（bonree）里建一份全局过程
每个需要采集执行计划的业务 schema 里再各建一份同名过程

注意：并非所有查询都支持执行计划。仅 SELECT / INSERT / UPDATE / DELETE / REPLACE 语句支持 EXPLAIN；BEGIN / COMMIT / SHOW / USE / ALTER 等无法生成有效的执行计划。

3.3.1 创建共享监控 schema 与全局过程

共用一个全局监控库 bonree，当查询没有明确的 schema 上下文时，会依赖此库下的全局过程

CREATE SCHEMA IF NOT EXISTS bonree;

GRANT EXECUTE ON bonree.* TO 'bonree'@'%';

DELIMITER $$
CREATE PROCEDURE bonree.explain_statement (IN query TEXT)
    SQL SECURITY DEFINER
BEGIN
    SET @explain := CONCAT('EXPLAIN FORMAT=json ', query);
    PREPARE stmt FROM @explain;
    EXECUTE stmt;
    DEALLOCATE PREPARE stmt;
END $$
DELIMITER ;

SQL SECURITY DEFINER：定义者通常是 root@'localhost'，监控用户仅需 EXECUTE 权限即可拿到原本属于 DEFINER 的库表读取权限（前提：DEFINER 本身对业务表有读权限），可避免给 bonree 用户直接 GRANT 业务库的 SELECT 权限。

注：如果是非bonree.explain_statement这种默认agent schema名下的全局explain存储过程的，请在mysql.d/conf.yaml配置中修改成自定义agent schema名下的存储过程，假设上面创建的schema是agent，用agent替代bonree，那么agent.explain_statement需配置如下：

instances:
  - host: 127.0.0.1         
    port: 3306             
    username: bonree
    password: '<PASSWORD>' 
    dbm: true 
    query_samples:
      # FQ_PROCEDURE 用的全局过程
      fully_qualified_explain_procedure: agent.explain_statement  # 默认值：bonree.explain_statement

3.3.2 在每个业务 schema 中创建同名过程

将 <YOUR_SCHEMA> 替换为实际业务库名，对每个要采集执行计划的数据库执行以下 SQL，以创建 explain_statement 存储过程：

DELIMITER $$
CREATE PROCEDURE <YOUR_SCHEMA>.explain_statement(IN query TEXT)
    SQL SECURITY DEFINER
BEGIN
    SET @explain := CONCAT('EXPLAIN FORMAT=json ', query);
    PREPARE stmt FROM @explain;
    EXECUTE stmt;
    DEALLOCATE PREPARE stmt;
END $$
DELIMITER ;
GRANT EXECUTE ON PROCEDURE <YOUR_SCHEMA>.explain_statement TO 'bonree'@'%';

3.3.3 特殊说明

通常会优先使用实际业务库名下的存储过程，失败会使用全局bonree库下的存储过程，如果都失败，可能需要把业务库 SELECT 权限也给 bonree（相当于裸 EXPLAIN，安全等级低，不推荐）：

GRANT SELECT ON <APP_SCHEMA>.* TO 'bonree'@'%';

3.4 `performance_schema` 开启

开启性能表是为了 DBM 数据采集，可通过配置文件配置开启，也可在运行时开启。

3.4.1 配置中开启

在 my.cnf [mysqld] 段：

[mysqld]
performance_schema = ON
performance-schema-consumer-events-statements-current = ON
performance-schema-consumer-events-statements-history = ON
performance-schema-consumer-events-statements-history-long = ON
performance-schema-consumer-events-waits-current = ON

需要配置采集的sql语句长度可以添加下面配置，不然默认是1024个字符：

max_digest_length = 4096
performance_schema_max_digest_length = 4096
performance_schema_max_sql_text_length = 4096

注：修改后需重启数据库生效。

3.4.2 运行时开启：

DELIMITER $$
CREATE PROCEDURE bonree.enable_events_statements_consumers()
    SQL SECURITY DEFINER
BEGIN
    UPDATE performance_schema.setup_consumers SET enabled='YES' WHERE name LIKE 'events_statements_%';
    UPDATE performance_schema.setup_consumers SET enabled='YES' WHERE name = 'events_waits_current';
END $$
DELIMITER ;
GRANT EXECUTE ON PROCEDURE bonree.enable_events_statements_consumers TO bonree@'%';

注：运行时动态开启仅对 consumer 有效。max_digest_length 等参数仍需在 my.cnf 中配置并重启才能生效。

参数说明： MySQL >= 5.7 时：

参数	值	说明
`performance_schema`	`ON`	必需开启。启用 Performance Schema。
`max_digest_length`	`4096`	按需设置。用于采集更长的 SQL 语句。若保持默认值（1024），超过 1024 字符的查询将无法被采集。
`performance_schema_max_digest_length`	`4096`	必须与 `max_digest_length` 保持一致。
`performance_schema_max_sql_text_length`	`4096`	必须与 `max_digest_length` 保持一致。 MySQL > 5.6时有此项
`performance-schema-consumer-events-statements-current`	`ON`	必需开启。启用对当前正在执行查询的监控。
`performance-schema-consumer-events-waits-current`	`ON`	必需开启。启用 wait 事件采集。
`performance-schema-consumer-events-statements-history-long`	`ON`	推荐开启。在所有线程上跟踪更多近期查询，有助于捕获低频查询的执行详情。
`performance-schema-consumer-events-statements-history`	`ON`	可选。按线程跟踪近期查询历史，有助于捕获低频查询的执行详情。

注：如果上述创建非 bonree.enable_events_statements_consumers默认命名，请在mysql.d/conf.yaml配置中修改成自己自定义的存储过程名，假设上面用agent替代bonree，那么agent.enable_events_statements_consumers 需配置如下：

instances:
  - host: 127.0.0.1         
    port: 3306             
    username: bonree     
    password: '<PASSWORD>' 
    dbm: true 
    query_samples:
      # 若 consumer 开启过程建在 agent 下
      events_statements_enable_procedure: agent.enable_events_statements_consumers  # 默认值：bonree.enable_events_statements_consumers

3.5 自检脚本

刷新后查看授予的权限：

FLUSH PRIVILEGES;
SHOW GRANTS FOR 'bonree'@'%';

mysql -u bonree --password='<UNIQUEPASSWORD>' <<'SQL'
SELECT VERSION();
SELECT @@performance_schema;

SELECT NAME, ENABLED
  FROM performance_schema.setup_consumers
 WHERE NAME LIKE 'events_statements_%' OR NAME = 'events_waits_current';

SELECT COUNT(*) AS timed_statement_instruments
  FROM performance_schema.setup_instruments
 WHERE NAME LIKE 'statement/%' AND ENABLED = 'YES' AND TIMED = 'YES';

SHOW GRANTS FOR CURRENT_USER();
SQL

期望输出：

@@performance_schema = 1。
events_statements_current / history / history_long 全是 YES。
events_waits_current = YES。
timed statement instruments 数量 ≥ 1。
GRANTS 至少包含 PROCESS、REPLICATION CLIENT、SELECT ON performance_schema.*。

4. Agent 端配置：`mysql.d/conf.yaml`

4.1 最小配置

文件路径：

OS	路径
Linux	`${APM_HOME}/integration/conf/integration.d/mysql.d/conf.yaml`

instances:
  - host: 127.0.0.1         # 连接数据库的主机ip或域名，默认为本机：localhost或127.0.0.1
    port: 3306              # 连接数据库的端口，mysql默认为3306
    username: bonree        # 探针访问数据库设置的用户名，需与数据库端配置的一致
    password: '<PASSWORD>'  # 用户访问数据库的密码，比如设置为:'Bonree@123'，需与数据库端配置的一致
    dbm: false              # true：开启数据库性能监控，false: 关闭，默认值：false
    # tags:
    #   - cluster:cluster_name        # 上报数据时需要带的自定义集群名标签
  # 可配置多个数据库监控实例，比如添加：
  # - host: 10.1.1.1
  #   port: 3307              # 假设mysql映射的访问端口为3307
  #   username: bonree
  #   password: '<PASSWORD>'
  #   dbm: true
  #   #tags:
  #     #- cluster:prod-mariadb-cluster

4.2 开启 Schema 采集

instances:
  - host: 127.0.0.1
    port: 3306
    username: bonree
    password: '<PASSWORD>'
    dbm: true                         # 开启 DBM 采集
    # tags:
    #   - cluster:cluster_name        # 上报数据时需要带的自定义集群名标签

    collect_schemas:
      enabled: true                   # 大库慎开；开后会查 information_schema 列出库/表/列/索引，默认false，即默认不开启

4.3 配置生效

配置热生效，修改后如未生效，可重启 SmartAgent（执行bash命令：systemctl restart bonree-agent）。

常见场景

新接入 MySQL 并开启数据库性能观测

完成监控用户授权与 performance_schema 配置，在 Agent 实例中设置 dbm: true，再通过自检脚本和数据库观测页面验证数据。

需要查看 SQL 执行计划

在 bonree 共享监控库及目标业务库创建 explain_statement，并授予监控用户执行权限；使用自定义 schema 时同步修改 Agent 配置。

需要将慢 SQL 关联到应用服务或调用链

在 ONE 平台创建数据库端到端关联规则，根据分析深度选择 Service 或 Full 传播模式，并在业务低峰期评估 Full 模式的性能影响。

5. 服务、调用链关联

应用服务（比如java服务）访问受监控的数据库时，可以在Bonree ONE平台开启不同传播模式，开启/关闭注入SQL注释达到服务或调用链的关联/取消关联。

注：当前关联仅支持受java探针监控的java服务，后续会支持其他探针监控的服务

5.1 配置步骤

进入Bonree ONE平台首页->部署配置->规则配置->数据采集->数据库->创建（创建端到端关联规则）->选择服务范围->选择数据库类型->选择传播模式（即关联模式，默认是关闭，可选关闭、Full、Service三种模式）

5.2 传播模式说明

关闭模式：代表不注入任何注释，数据库功能无法追溯到上游服务以及调用链。
Service模式：代表仅在SQL注释中注入服务级信息，提供基础的关联分析能力，不支持关联调用链。
Full模式：代表注入完整服务和Trace信息，数据库功能可以追溯到上游服务以及调用链等相关信息。

5.3 注意事项

关联前提：并非所有语句都能关联。仅当 SQL 注释成功写入数据库性能表后，才能采集到关联信息（例如长耗时、阻塞类语句）。
性能影响：SQL 注释本身对网络传输、解析与 CPU 开销通常较小；但 Full 模式可能影响执行计划缓存（如缓存不命中、硬解析），请谨慎开启。
Prepared Statement 注入：仅对 PostgreSQL 生效。开启后，每次 PreparedStatement 执行前都会通过连接级 ApplicationName 携带 Trace 信息。该操作可能产生额外的 session 属性更新和网络往返，在高频 SQL 场景下增加执行延迟，建议评估性能后开启。
注释位置：用于复杂环境的特殊兼容；默认在 SQL 之前注入注释。

快速上手​

1. 支持范围​

数据库支持版本：​

支持系统架构：​

探针支持版本：​

2. 部署​

3. MySQL 端配置：用户与权限​

3.1 创建 bonree 用户​

3.2 基础授权​

3.3 DBM 执行计划采集配置：EXPLAIN 存储过程​

3.3.1 创建共享监控 schema 与全局过程​

3.3.2 在每个业务 schema 中创建同名过程​

3.3.3 特殊说明​

3.4 performance_schema 开启​

3.4.1 配置中开启​

3.4.2 运行时开启：​

3.5 自检脚本​

4. Agent 端配置：mysql.d/conf.yaml​

4.1 最小配置​

4.2 开启 Schema 采集​

4.3 配置生效​

常见场景​

5. 服务、调用链关联​

5.1 配置步骤​

5.2 传播模式说明​

5.3 注意事项​