慢 SQL 监控使用指南

一、功能说明

DLZ-DB 内置了慢 SQL 监控功能，当 SQL 执行时间超过设定的阈值时，会以 WARN 级别输出日志，帮助快速定位性能问题。

二、配置方式

2.1 Spring Boot 配置

dlz:
  db:
    log:
      show-run-sql: true           # 显示完整 SQL（推荐开启）
      slow-sql-threshold: 1000     # 慢 SQL 阈值（毫秒），0 表示不启用

2.2 Solon 配置

dlz.db:
  log.show-run-sql: true
  log.slow-sql-threshold: 1000

三、工作原理

1. 执行计时：每次 SQL 执行时自动记录开始时间
2. 耗时计算：执行完成后计算实际耗时
3. 级别判断：
   • 耗时 ≤ 阈值：以 INFO 级别输出
   • 耗时 > 阈值：以 WARN 级别输出
4. 日志输出：包含完整 SQL、耗时、调用位置等信息

四、示例输出

4.1 正常 SQL（INFO 级别）

INFO [main] c.d.db.util.DbLogUtil - query 50ms sql:SELECT * FROM user WHERE id = 1

4.2 慢 SQL（WARN 级别）

WARN [main] c.d.db.util.DbLogUtil - query 1250ms sql:SELECT * FROM user WHERE status = 1 AND create_time > '2024-01-01' ORDER BY create_time DESC

4.3 带调用位置的日志

dlz:
  db:
    log:
      show-caller: true            # 显示调用位置
      slow-sql-threshold: 1000

输出：

WARN [main] c.d.db.util.DbLogUtil - query 1250ms sql:SELECT * FROM user WHERE status = 1
 caller:(UserService.java:45)

五、阈值设置建议

环境	推荐值	说明
开发环境	0 或 5000ms	不启用或较大值，避免干扰开发
测试环境	1000ms	发现潜在性能问题
预发布环境	500ms	严格监控性能
生产环境	500-1000ms	及时发现慢查询

六、使用场景

6.1 开发阶段优化

// 发现慢查询后，可以针对性优化
List<User> users = DB.Pojo.select(User.class)
    .eq(User::getStatus, 1)
    .orderByDesc(User::getCreateTime)
    .queryBeanList();
// WARN 日志提示：query 1500ms
// → 考虑添加索引或优化查询条件

6.2 批量操作监控

// 批量插入时监控每批的耗时
DB.Batch.insert(users, 500);
// 如果某批耗时超过阈值，会输出 WARN 日志

6.3 复杂查询调优

// 预设 SQL 中的复杂查询
List<ResultMap> report = DB.Sql.select("key.report.monthly")
    .addPara("year", 2024)
    .addPara("month", 1)
    .queryList();
// WARN 日志提示：query 2300ms
// → 需要优化 SQL 或添加索引

七、注意事项

7.1 默认不启用

slow-sql-threshold 默认值为 0，表示不启用慢 SQL 监控。需要显式配置才能生效。

7.2 不影响性能

慢 SQL 监控仅在日志输出时增加少量开销，不会影响 SQL 执行性能。

7.3 与其他日志配置配合

dlz:
  db:
    log:
      show-run-sql: true           # 必须开启，否则看不到完整 SQL
      show-caller: true            # 建议开启，方便定位代码
      slow-sql-threshold: 1000     # 慢 SQL 阈值

7.4 日志级别

• 确保日志框架（logback/log4j2）的 WARN 级别已启用
• 生产环境建议将 DLZ-DB 的日志级别设置为 WARN，只输出慢 SQL

<!-- logback.xml -->
<logger name="com.dlz.db" level="WARN"/>

八、常见问题

Q1: 为什么设置了阈值但没有 WARN 日志？

A: 检查以下几点：

1. 确认 show-run-sql 已开启
2. 确认日志级别允许 WARN 输出
3. 确认 SQL 执行时间确实超过阈值
4. 检查配置是否正确加载

Q2: 如何临时关闭慢 SQL 监控？

A: 将阈值设置为 0：

dlz:
  db:
    log:
      slow-sql-threshold: 0

Q3: 能否针对不同数据源设置不同阈值？

A: 当前版本不支持，所有数据源共用同一阈值。如需差异化监控，建议在应用层实现。

Q4: 慢 SQL 日志会影响性能吗？

A: 影响极小。仅在 SQL 执行完成后增加一次时间比较和可能的日志输出，对整体性能影响可忽略。

九、最佳实践

1. 分阶段设置阈值

   • 开发初期：不启用（0）
   • 功能开发完成：1000ms
   • 性能优化阶段：500ms
   • 生产环境：500-1000ms

2. 结合调用位置分析

   dlz:
     db:
       log:
         show-caller: true          # 开启调用位置
         slow-sql-threshold: 1000

3. 定期审查慢 SQL 日志

   • 每周审查一次 WARN 日志
   • 建立慢 SQL 优化清单
   • 跟踪优化效果

4. 与数据库监控工具配合

   • DLZ-DB 慢 SQL 日志：应用层监控
   • MySQL slow query log：数据库层监控
   • APM 工具：全链路监控

---

文档版本： v1.0
最后更新： 2026-05-06