Files

该功能默认关闭

2025-12-17 14:09:02 +08:00

6.6 KiB

Raw Blame History

慢查询监控实现指南

概述

我们已经完整实现了数据库慢查询监控系统，包括：

✅ 慢查询自动检测和收集（默认关闭）
✅ 实时性能监控和统计
✅ 详细的文本和HTML报告生成
✅ 优化建议和性能分析
✅ 用户可选的启用/禁用开关

快速启用

方法 1：配置文件启用（推荐）

编辑 config/bot_config.toml：

[database]
enable_slow_query_logging = true  # 改为 true 启用
slow_query_threshold = 0.5        # 设置阈值（秒）

方法 2：代码动态启用

from src.common.database.utils import enable_slow_query_monitoring

# 启用监控
enable_slow_query_monitoring()

# 禁用监控
disable_slow_query_monitoring()

# 检查状态
if is_slow_query_monitoring_enabled():
    print("慢查询监控已启用")

配置

bot_config.toml

[database]
# 慢查询监控配置（默认关闭，需要时设置 enable_slow_query_logging = true 启用）
enable_slow_query_logging = false    # 是否启用慢查询日志（设置为 true 启用）
slow_query_threshold = 0.5           # 慢查询阈值（秒）
query_timeout = 30                   # 查询超时时间（秒）
collect_slow_queries = true          # 是否收集慢查询统计
slow_query_buffer_size = 100         # 慢查询缓冲大小（最近N条）

推荐参数：

生产环境（推荐）：enable_slow_query_logging = false - 最小性能开销
测试环境：enable_slow_query_logging = true + slow_query_threshold = 0.5
开发环境：enable_slow_query_logging = true + slow_query_threshold = 0.1 - 捕获所有慢查询

使用方式

1. 自动监控（推荐）

启用后，所有使用 @measure_time() 装饰器的函数都会被监控：

from src.common.database.utils import measure_time

@measure_time()  # 使用配置中的阈值
async def my_database_query():
    return result

@measure_time(log_slow=1.0)  # 自定义阈值
async def another_query():
    return result

2. 手动记录慢查询

from src.common.database.utils import record_slow_query

record_slow_query(
    operation_name="custom_query",
    execution_time=1.5,
    sql="SELECT * FROM users WHERE id = ?",
    args=(123,)
)

3. 获取慢查询报告

from src.common.database.utils import get_slow_query_report

report = get_slow_query_report()

print(f"总慢查询数: {report['total']}")
print(f"阈值: {report['threshold']}")

for op in report['top_operations']:
    print(f"{op['operation']}: {op['count']} 次")

4. 在代码中使用分析工具

from src.common.database.utils.slow_query_analyzer import SlowQueryAnalyzer

# 生成文本报告
text_report = SlowQueryAnalyzer.generate_text_report()
print(text_report)

# 生成HTML报告
SlowQueryAnalyzer.generate_html_report("reports/slow_query.html")

# 获取最慢的查询
slowest = SlowQueryAnalyzer.get_slowest_queries(limit=20)
for query in slowest:
    print(f"{query.operation_name}: {query.execution_time:.3f}s")

输出示例

启用时的初始化

✅ 慢查询监控已启用 (阈值: 0.5s, 缓冲: 100)

运行时的慢查询告警

🐢 get_user_by_id 执行缓慢: 0.752s (阈值: 0.500s)

关闭时的性能报告（仅在启用时输出）

============================================================
数据库性能统计
============================================================

操作统计:
  get_user_by_id: 次数=156, 平均=0.025s, 最小=0.001s, 最大=1.203s, 错误=0, 慢查询=3

缓存:
  命中=8923, 未命中=1237, 命中率=87.82%

整体:
  错误率=0.00%
  慢查询总数=3
  慢查询阈值=0.500s

🐢 慢查询报告:
  按操作排名（Top 10）:
    1. get_user_by_id: 次数=3, 平均=0.752s, 最大=1.203s

常见问题

Q1: 如何知道监控是否启用了？

from src.common.database.utils import is_slow_query_monitoring_enabled

if is_slow_query_monitoring_enabled():
    print("✅ 慢查询监控已启用")
else:
    print("❌ 慢查询监控已禁用")

Q2: 如何临时启用/禁用？

from src.common.database.utils import enable_slow_query_monitoring, disable_slow_query_monitoring

# 临时启用
enable_slow_query_monitoring()

# ... 执行需要监控的代码 ...

# 临时禁用
disable_slow_query_monitoring()

Q3: 默认关闭会影响性能吗？

完全不会。关闭后没有任何性能开销。

Q4: 监控数据会持久化吗？

目前使用内存缓冲（默认最近 100 条），系统关闭时会输出报告。

最佳实践

1. 生产环境配置

# config/bot_config.toml
[database]
enable_slow_query_logging = false    # 默认关闭

只在需要调试性能问题时临时启用：

from src.common.database.utils import enable_slow_query_monitoring

# 在某个插件中启用
enable_slow_query_monitoring()

# 执行和监控需要优化的代码

disable_slow_query_monitoring()

2. 开发/测试环境配置

# config/bot_config.toml
[database]
enable_slow_query_logging = true     # 启用
slow_query_threshold = 0.5           # 500ms

3. 使用 @measure_time() 装饰器

# ✅ 推荐：自动监控所有 I/O 操作
@measure_time()
async def get_user_info(user_id: str):
    return await user_crud.get_by_id(user_id)

技术细节

核心组件

文件	职责
`monitoring.py`	核心监控器，启用/禁用逻辑
`decorators.py`	`@measure_time()` 装饰器
`slow_query_analyzer.py`	分析和报告生成

启用流程

enable_slow_query_logging = true
           ↓
main.py: set_slow_query_config()
           ↓
get_monitor().enable()
           ↓
is_enabled() = True
           ↓
record_operation() 检查并记录慢查询
           ↓
输出 🐢 警告信息

禁用流程

enable_slow_query_logging = false
           ↓
is_enabled() = False
           ↓
record_operation() 不记录慢查询
           ↓
无性能开销

性能影响

启用时

CPU 开销: < 0.1%（仅在超过阈值时记录）
内存开销: ~50KB（缓冲 100 条慢查询）

禁用时

CPU 开销: ~0%
内存开销: 0 KB（不收集数据）

结论：可以安全地在生产环境中默认禁用，需要时启用。

下一步优化

自动启用：在检测到性能问题时自动启用
告警系统：当慢查询比例超过阈值时发送告警
Prometheus 集成：导出监控指标
Grafana 仪表板：实时可视化

文档更新: 2025-12-17
状态: ✅ 默认关闭，用户可选启用

6.6 KiB Raw Blame History Unescape Escape