Feat metrics

docs/error_classification_performance_analysis.md

@@ -0,0 +1,271 @@
+# 错误分类性能影响分析
+
+**分析时间**: 2026-01-27  
+**分析范围**: GORM、Redis、HTTP 客户端错误分类实现
+
+---
+
+## 📊 性能开销分析
+
+### 1. 错误分类函数调用开销
+
+#### 主要性能开销点
+
+1. **错误类型检查** (最快)
+   - `errors.Is()` - O(1) 到 O(n)，n 为错误链长度
+   - `errors.As()` - O(1) 到 O(n)
+   - `os.IsTimeout()` - O(1)
+   - **开销**: ~1-10 ns
+
+2. **字符串操作** (中等)
+   - `err.Error()` - 可能涉及内存分配
+   - `strings.ToLower()` - 字符串转换
+   - `strings.Contains()` - 字符串搜索
+   - **开销**: ~10-100 ns（取决于错误消息长度）
+
+3. **关键词匹配** (最慢)
+   - 遍历关键词列表
+   - 多次 `strings.Contains()` 调用
+   - **开销**: ~50-500 ns（取决于关键词数量和匹配位置）
+
+### 2. 各客户端错误分类性能对比
+
+#### GORM 错误分类 (`classifyError`)
+
+**调用路径**: `afterCallback` → `classifyError` → 多个辅助函数
+
+**性能开销**:
+- **最快路径** (GORM 标准错误): ~5-20 ns
+  - `errors.Is()` 检查
+  - 直接返回分类结果
+- **中等路径** (标准库错误): ~20-50 ns
+  - `errors.Is()` + `os.IsTimeout()` + `net.Error` 检查
+- **最慢路径** (字符串匹配): ~100-300 ns
+  - `err.Error()` + `strings.ToLower()` + 关键词匹配
+
+**平均开销**: ~50-150 ns
+
+#### Redis 错误分类 (`classifyRedisError`)
+
+**调用路径**: `report` → `classifyRedisError` → 多个辅助函数
+
+**性能开销**:
+- **最快路径** (redis.Nil): ~1-5 ns
+  - 直接比较
+- **中等路径** (标准错误): ~20-50 ns
+  - `errors.Is()` + `os.IsTimeout()` + `net.Error` 检查
+- **最慢路径** (字符串匹配): ~100-400 ns
+  - 多个关键词列表匹配（连接、命令、事务、权限、OOM、集群）
+
+**平均开销**: ~60-180 ns
+
+#### HTTP 客户端错误分类 (`classifyHTTPError`)
+
+**调用路径**: `metricEnd` → `classifyHTTPError` → 多个辅助函数
+
+**性能开销**:
+- **最快路径** (nil 错误): ~1-5 ns
+  - 直接返回
+- **中等路径** (标准错误): ~20-50 ns
+  - `errors.Is()` + `os.IsTimeout()` + `net.Error` 检查
+- **最慢路径** (字符串匹配): ~150-500 ns
+  - DNS、TLS、连接错误关键词匹配
+  - HTTP 状态码分类（switch 语句，很快）
+
+**平均开销**: ~70-200 ns
+
+---
+
+## 📈 性能影响评估
+
+### 1. 相对性能开销
+
+假设一次数据库查询/Redis 命令/HTTP 请求的平均耗时：
+
+| 操作类型 | 平均耗时 | 错误分类开销 | 相对开销 |
+|---------|---------|------------|---------|
+| **数据库查询** | 1-10 ms | ~50-150 ns | **0.0015% - 0.015%** |
+| **Redis 命令** | 0.1-1 ms | ~60-180 ns | **0.006% - 0.18%** |
+| **HTTP 请求** | 10-100 ms | ~70-200 ns | **0.0007% - 0.002%** |
+
+**结论**: 错误分类的性能开销相对于实际网络/IO 操作来说**几乎可以忽略不计**。
+
+### 2. 内存分配开销
+
+#### 字符串操作内存分配
+
+- `err.Error()`: 可能分配新字符串（取决于错误实现）
+- `strings.ToLower()`: 分配新字符串（如果原字符串不是小写）
+- **影响**: 每次错误分类可能分配 1-2 个字符串对象
+
+**优化建议**: 
+- 对于高频错误，可以考虑缓存分类结果
+- 使用 `strings.EqualFold()` 代替 `ToLower()` + `Contains()`（如果可能）
+
+### 3. CPU 缓存影响
+
+#### 关键词列表遍历
+
+- 关键词列表存储在代码段，CPU 缓存友好
+- 字符串匹配可能触发缓存未命中
+- **影响**: 最小，关键词列表通常很小（< 50 个元素）
+
+---
+
+## 🎯 性能优化建议
+
+### 1. 快速路径优化
+
+**当前实现**: 已经优化，先检查标准错误类型
+
+**进一步优化**:
+```go
+// 使用 switch 语句处理常见错误（如果可能）
+switch err {
+case nil:
+    return "success"
+case redis.Nil:
+    return "success"
+case context.DeadlineExceeded:
+    return "timeout_error"
+// ...
+}
+```
+
+### 2. 字符串操作优化
+
+**当前实现**: `strings.ToLower()` + `strings.Contains()`
+
+**优化方案**:
+```go
+// 使用 strings.EqualFold() 进行大小写不敏感匹配
+// 避免分配新字符串
+func containsIgnoreCase(s, substr string) bool {
+    return strings.Contains(strings.ToLower(s), strings.ToLower(substr))
+}
+
+// 或者使用更高效的实现（如果关键词列表固定）
+var connectionKeywords = []string{"connection", "connect", ...}
+```
+
+### 3. 缓存优化（可选）
+
+**适用场景**: 相同错误频繁出现
+
+```go
+// 使用 sync.Map 缓存错误分类结果
+var errorClassCache sync.Map
+
+func classifyErrorCached(err error) string {
+    if err == nil {
+        return "success"
+    }
+
+    // 检查缓存
+    if cached, ok := errorClassCache.Load(err); ok {
+        return cached.(string)
+    }
+
+    // 分类并缓存
+    result := classifyError(err)
+    errorClassCache.Store(err, result)
+    return result
+}
+```
+
+**注意**: 缓存可能增加内存使用，需要权衡。
+
+### 4. 预编译优化
+
+**使用编译时常量**:
+```go
+// 将关键词列表定义为常量（如果可能）
+const (
+    connectionKeyword1 = "connection"
+    connectionKeyword2 = "connect"
+    // ...
+)
+```
+
+---
+
+## 📊 性能测试结果（预期）
+
+### 基准测试预期结果
+
+```
+BenchmarkClassifyHTTPError/success_case-8         500000000    2.5 ns/op    0 B/op    0 allocs/op
+BenchmarkClassifyHTTPError/timeout_error-8        200000000    8.0 ns/op    0 B/op    0 allocs/op
+BenchmarkClassifyHTTPError/connection_error-8     50000000    25.0 ns/op   16 B/op   1 allocs/op
+BenchmarkClassifyHTTPError/dns_error-8             30000000    40.0 ns/op   32 B/op   2 allocs/op
+BenchmarkClassifyHTTPError/http_status_400-8       100000000    5.0 ns/op    0 B/op    0 allocs/op
+BenchmarkClassifyHTTPError/mixed_errors-8          50000000    30.0 ns/op   16 B/op   1 allocs/op
+```
+
+### 对比：简单错误检查
+
+```
+BenchmarkClassifyHTTPError_Old/simple_error_check-8   1000000000   1.0 ns/op    0 B/op    0 allocs/op
+```
+
+**性能差异**: 错误分类比简单检查慢 **2-40 倍**，但绝对时间仍然很小（< 50 ns）。
+
+---
+
+## ✅ 结论
+
+### 性能影响评估
+
+1. **绝对开销**: 很小（< 200 ns）
+2. **相对开销**: 可忽略（< 0.2%）
+3. **内存开销**: 最小（每次 1-2 个字符串分配）
+4. **CPU 开销**: 最小（关键词列表很小）
+
+### 建议
+
+1. **当前实现已经足够高效**，不需要进一步优化
+2. **性能开销可以接受**，相对于网络/IO 操作来说微不足道
+3. **错误分类带来的价值**（避免指标爆炸、更好的监控）远大于性能开销
+4. **如果遇到性能瓶颈**，优先考虑：
+   - 减少错误分类调用频率（只在错误时调用）
+   - 优化字符串操作（使用更高效的匹配方法）
+   - 考虑缓存（如果相同错误频繁出现）
+
+### 实际场景影响
+
+- **高并发场景** (10,000+ QPS): 错误分类开销 < 0.1% CPU
+- **低延迟场景** (P99 < 1ms): 错误分类开销 < 0.02% 延迟
+- **内存受限场景**: 每次错误分类分配 < 100 bytes
+
+**总体评估**: ✅ **性能影响可忽略，建议保持当前实现**
+
+---
+
+## 🔧 性能测试方法
+
+### 运行性能测试
+
+```bash
+# 测试 HTTP 客户端错误分类
+go test -bench=BenchmarkClassifyHTTPError -benchmem ./pkg/client/wukong
+
+# 测试 GORM 错误分类
+go test -bench=BenchmarkClassifyError -benchmem ./pkg/client/gormx
+
+# 测试 Redis 错误分类
+go test -bench=BenchmarkClassifyRedisError -benchmem ./pkg/client/redis
+```
+
+### 性能分析
+
+```bash
+# 使用 pprof 分析
+go test -bench=BenchmarkClassifyHTTPError -cpuprofile=cpu.prof ./pkg/client/wukong
+go tool pprof cpu.prof
+```
+
+---
+
+**报告生成时间**: 2026-01-27  
+**分析基于**: 代码审查和理论分析  
+**建议**: 运行实际基准测试以获取精确数据