253 lines
6.3 KiB
Markdown
253 lines
6.3 KiB
Markdown
# SQL健康监控使用指南
|
||
|
||
## 概述
|
||
|
||
本项目已集成了简单而高效的SQL健康监控功能，可以自动记录每条SQL语句的执行时间、成功状态和错误信息。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 自动记录SQL执行时间（毫秒级精度）
|
||
- ✅ 记录SQL执行成功/失败状态
|
||
- ✅ 记录错误信息和影响行数
|
||
- ✅ 支持慢查询检测
|
||
- ✅ 提供统计信息（成功率、平均耗时等）
|
||
- ✅ 提供Web仪表板实时监控
|
||
- ✅ 内存高效（可配置最大记录数）
|
||
|
||
## API接口
|
||
|
||
### 1. 获取SQL执行统计信息
|
||
```
|
||
GET /api/sql-health/stats
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"total_queries": 1250,
|
||
"success_queries": 1240,
|
||
"failed_queries": 10,
|
||
"success_rate": "99.20",
|
||
"avg_duration_ms": 45,
|
||
"max_duration_ms": 2300,
|
||
"min_duration_ms": 2,
|
||
"last_update": "2024-01-15 14:30:25"
|
||
},
|
||
"timestamp": "2024-01-15 14:30:25"
|
||
}
|
||
```
|
||
|
||
### 2. 获取最近的SQL执行记录
|
||
```
|
||
GET /api/sql-health/recent?limit=50
|
||
```
|
||
|
||
参数：
|
||
- `limit`: 返回记录数量，默认50，最大500
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 1001,
|
||
"query": "SELECT id, book_name FROM book_center WHERE vio_book = ? ORDER BY id DESC LIMIT ? OFFSET ?",
|
||
"duration_ms": 23,
|
||
"timestamp": "2024-01-15T14:30:25Z",
|
||
"success": true,
|
||
"error": "",
|
||
"endpoint": "/api/bookBase/GetBookBaseInfoOptimized",
|
||
"rows_affected": 0
|
||
}
|
||
],
|
||
"count": 50,
|
||
"limit": 50
|
||
},
|
||
"timestamp": "2024-01-15 14:30:25"
|
||
}
|
||
```
|
||
|
||
### 3. 获取慢查询
|
||
```
|
||
GET /api/sql-health/slow-queries?threshold=1000
|
||
```
|
||
|
||
参数：
|
||
- `threshold`: 慢查询阈值（毫秒），默认1000ms
|
||
|
||
### 4. 获取失败查询
|
||
```
|
||
GET /api/sql-health/failed-queries
|
||
```
|
||
|
||
### 5. 清空记录
|
||
```
|
||
POST /api/sql-health/clear
|
||
```
|
||
|
||
### 6. Web仪表板
|
||
```
|
||
GET /api/sql-health/dashboard
|
||
```
|
||
|
||
访问此URL可以查看实时的SQL健康监控仪表板。
|
||
|
||
## 在代码中使用SQL监控
|
||
|
||
### 1. 查询操作（返回多行）
|
||
```go
|
||
func (bc *BookCenterController) YourQueryMethod(c *gin.Context) {
|
||
query := "SELECT * FROM book_center WHERE category = ?"
|
||
endpoint := c.FullPath() // 获取当前接口路径
|
||
|
||
// 使用监控执行查询
|
||
rows, err := MonitorQuery(bc.db, query, endpoint, "小说")
|
||
if err != nil {
|
||
c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
|
||
return
|
||
}
|
||
defer rows.Close()
|
||
|
||
// 处理结果...
|
||
}
|
||
```
|
||
|
||
### 2. 单行查询操作
|
||
```go
|
||
func (bc *BookCenterController) GetBookByISBN(c *gin.Context) {
|
||
isbn := c.Query("isbn")
|
||
query := "SELECT id, book_name, author FROM book_center WHERE isbn = ?"
|
||
endpoint := c.FullPath()
|
||
|
||
// 使用监控执行单行查询
|
||
row := MonitorQueryRow(bc.db, query, endpoint, isbn)
|
||
|
||
var id int64
|
||
var bookName, author string
|
||
if err := row.Scan(&id, &bookName, &author); err != nil {
|
||
c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
|
||
return
|
||
}
|
||
|
||
// 返回结果...
|
||
}
|
||
```
|
||
|
||
### 3. 更新/插入/删除操作
|
||
```go
|
||
func (bc *BookCenterController) UpdateBook(c *gin.Context) {
|
||
query := "UPDATE book_center SET book_name = ? WHERE id = ?"
|
||
endpoint := c.FullPath()
|
||
|
||
// 使用监控执行更新操作
|
||
result, err := MonitorExec(bc.db, query, endpoint, "新书名", 123)
|
||
if err != nil {
|
||
c.JSON(http.StatusInternalServerError, gin.H{"error": "更新失败"})
|
||
return
|
||
}
|
||
|
||
rowsAffected, _ := result.RowsAffected()
|
||
c.JSON(http.StatusOK, gin.H{
|
||
"message": "更新成功",
|
||
"rows_affected": rowsAffected,
|
||
})
|
||
}
|
||
```
|
||
|
||
## 监控配置
|
||
|
||
### 初始化配置
|
||
在 `main.go` 中的初始化：
|
||
```go
|
||
func main() {
|
||
// 初始化SQL监控器，最多保存1000条记录
|
||
InitSQLMonitor(1000)
|
||
|
||
// ... 其他初始化代码
|
||
}
|
||
```
|
||
|
||
### 自定义配置
|
||
可以根据需要调整最大记录数：
|
||
```go
|
||
// 保存更多记录（适合高流量应用）
|
||
InitSQLMonitor(5000)
|
||
|
||
// 保存较少记录（适合内存受限环境）
|
||
InitSQLMonitor(500)
|
||
```
|
||
|
||
## 性能影响
|
||
|
||
- **内存占用**: 每条记录约占用200-500字节
|
||
- **CPU开销**: 每次SQL执行增加约0.1-0.5ms开销
|
||
- **并发安全**: 使用读写锁，支持高并发访问
|
||
- **自动清理**: 超过最大记录数时自动删除旧记录
|
||
|
||
## 监控指标说明
|
||
|
||
### 统计指标
|
||
- `total_queries`: 总查询数
|
||
- `success_queries`: 成功查询数
|
||
- `failed_queries`: 失败查询数
|
||
- `success_rate`: 成功率（百分比）
|
||
- `avg_duration_ms`: 平均执行时间（毫秒）
|
||
- `max_duration_ms`: 最大执行时间（毫秒）
|
||
- `min_duration_ms`: 最小执行时间（毫秒）
|
||
|
||
### 记录字段
|
||
- `id`: 记录唯一ID
|
||
- `query`: SQL查询语句
|
||
- `duration_ms`: 执行时间（毫秒）
|
||
- `timestamp`: 执行时间戳
|
||
- `success`: 是否成功
|
||
- `error`: 错误信息（如果有）
|
||
- `endpoint`: 调用的API接口
|
||
- `rows_affected`: 影响的行数（仅适用于INSERT/UPDATE/DELETE）
|
||
|
||
## 最佳实践
|
||
|
||
1. **接口标识**: 使用 `c.FullPath()` 作为endpoint参数，便于追踪问题
|
||
2. **错误处理**: 监控函数会自动记录错误，无需额外处理
|
||
3. **性能优化**: 对于非关键查询，可以考虑不使用监控以减少开销
|
||
4. **定期清理**: 在生产环境中定期调用清理接口，避免内存占用过多
|
||
5. **阈值设置**: 根据业务需求调整慢查询阈值
|
||
|
||
## 故障排查
|
||
|
||
### 常见问题
|
||
1. **监控器未初始化**: 确保在main函数中调用了 `InitSQLMonitor()`
|
||
2. **记录不显示**: 检查是否使用了 `MonitorQuery` 等监控函数
|
||
3. **内存占用过高**: 减少最大记录数或定期清理记录
|
||
|
||
### 调试技巧
|
||
- 查看控制台日志，监控函数会输出详细的执行信息
|
||
- 使用仪表板实时查看SQL执行情况
|
||
- 通过API接口获取详细的统计信息
|
||
|
||
## 示例场景
|
||
|
||
### 场景1: 性能优化
|
||
通过监控发现某个查询平均耗时过长，可以：
|
||
1. 查看慢查询接口找到具体SQL
|
||
2. 分析SQL执行计划
|
||
3. 添加合适的索引
|
||
4. 重新监控验证优化效果
|
||
|
||
### 场景2: 错误排查
|
||
当出现数据库错误时，可以：
|
||
1. 查看失败查询接口
|
||
2. 分析错误信息和SQL语句
|
||
3. 定位问题原因
|
||
4. 修复后验证
|
||
|
||
### 场景3: 容量规划
|
||
通过长期监控数据：
|
||
1. 分析查询频率和耗时趋势
|
||
2. 评估数据库负载
|
||
3. 制定扩容计划
|