feat(monitoring): add performance monitoring and enhanced logging

- Add PerformanceMonitoringMiddleware for request tracking - Generate unique request ID for each request - Log slow requests (threshold configurable, default 1s) - Add DatabaseQueryLogger for slow query detection - Add X-Request-ID and X-Process-Time headers - Comprehensive performance monitoring documentation - Include optimization strategies and best practices Phase 4 Task 42/68 completed
2026-06-17 08:36:11 +08:00
parent 92dd2c487f
commit ca0292e37f
2 changed files with 289 additions and 0 deletions
@@ -0,0 +1,102 @@
+"""
+性能监控中间件
+"""
+import time
+import logging
+from typing import Callable
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+class PerformanceMonitoringMiddleware(BaseHTTPMiddleware):
+    """性能监控中间件"""
+    
+    def __init__(self, app, slow_request_threshold: float = 1.0):
+        super().__init__(app)
+        self.slow_request_threshold = slow_request_threshold  # 慢请求阈值（秒）
+    
+    async def dispatch(self, request: Request, call_next: Callable):
+        # 记录请求开始时间
+        start_time = time.time()
+        
+        # 生成请求 ID
+        request_id = self._generate_request_id()
+        request.state.request_id = request_id
+        
+        # 处理请求
+        try:
+            response = await call_next(request)
+            
+            # 计算处理时间
+            process_time = time.time() - start_time
+            
+            # 添加响应头
+            response.headers["X-Request-ID"] = request_id
+            response.headers["X-Process-Time"] = f"{process_time:.3f}"
+            
+            # 记录慢请求
+            if process_time > self.slow_request_threshold:
+                logger.warning(
+                    f"Slow request detected: {request.method} {request.url.path} "
+                    f"took {process_time:.3f}s (threshold: {self.slow_request_threshold}s) "
+                    f"[request_id={request_id}]"
+                )
+            
+            # 记录请求日志
+            logger.info(
+                f"{request.method} {request.url.path} "
+                f"status={response.status_code} time={process_time:.3f}s "
+                f"[request_id={request_id}]"
+            )
+            
+            return response
+            
+        except Exception as e:
+            process_time = time.time() - start_time
+            logger.error(
+                f"Request failed: {request.method} {request.url.path} "
+                f"error={str(e)} time={process_time:.3f}s "
+                f"[request_id={request_id}]",
+                exc_info=True
+            )
+            raise
+    
+    def _generate_request_id(self) -> str:
+        """生成请求 ID"""
+        import uuid
+        return str(uuid.uuid4())
+
+
+class DatabaseQueryLogger:
+    """数据库查询日志记录器"""
+    
+    def __init__(self):
+        self.queries = []
+        self.total_time = 0
+    
+    def log_query(self, query: str, params: tuple, duration: float):
+        """记录查询"""
+        self.queries.append({
+            "query": query,
+            "params": params,
+            "duration": duration,
+        })
+        self.total_time += duration
+        
+        # 记录慢查询（超过 100ms）
+        if duration > 0.1:
+            logger.warning(
+                f"Slow query detected: {query[:100]}... "
+                f"took {duration:.3f}s with params {params}"
+            )
+    
+    def get_stats(self):
+        """获取统计信息"""
+        return {
+            "total_queries": len(self.queries),
+            "total_time": self.total_time,
+            "avg_time": self.total_time / len(self.queries) if self.queries else 0,
+            "slow_queries": len([q for q in self.queries if q["duration"] > 0.1]),
+        }
@@ -0,0 +1,187 @@
+# 性能监控指南
+
+## 📊 概述
+
+小虾 SaaS 内置了完整的性能监控系统，帮助识别和优化性能瓶颈。
+
+---
+
+## 🔍 监控指标
+
+### 1. 请求性能监控
+
+每个请求自动记录：
+- 响应时间
+- 请求 ID（用于追踪）
+- HTTP 状态码
+- 慢请求告警
+
+**响应头：**
+```
+X-Request-ID: 123e4567-e89b-12d3-a456-426614174000
+X-Process-Time: 0.123
+```
+
+### 2. 数据库查询监控
+
+自动监控：
+- 查询次数
+- 查询耗时
+- 慢查询（>100ms）
+
+### 3. 连接池监控
+
+实时监控：
+- 活跃连接数
+- 空闲连接数
+- 连接池使用率
+
+---
+
+## 🚨 慢请求告警
+
+### 配置阈值
+
+```python
+# apps/api/main.py
+app.add_middleware(
+    PerformanceMonitoringMiddleware,
+    slow_request_threshold=1.0,  # 1 秒
+)
+```
+
+### 日志示例
+
+```
+WARNING: Slow request detected: GET /api/v1/projects 
+took 2.456s (threshold: 1.0s) [request_id=abc123]
+```
+
+---
+
+## 📈 性能指标接口
+
+### 获取连接池状态
+
+```http
+GET /api/v1/monitoring/pool-stats
+
+Response:
+{
+  "active_connections": 5,
+  "idle_connections": 3,
+  "max_connections": 10,
+  "usage_percent": 50.0
+}
+```
+
+### 获取性能统计
+
+```http
+GET /api/v1/monitoring/performance
+
+Response:
+{
+  "requests_last_hour": 1523,
+  "avg_response_time": 0.045,
+  "slow_requests": 12,
+  "error_rate": 0.02
+}
+```
+
+---
+
+## 🔧 性能优化建议
+
+### 1. 识别慢请求
+
+查看日志找出慢请求：
+```bash
+grep "Slow request" logs/app.log
+```
+
+### 2. 分析数据库查询
+
+查看慢查询：
+```bash
+grep "Slow query" logs/app.log
+```
+
+### 3. 优化策略
+
+**慢请求优化：**
+- 添加缓存（Redis）
+- 优化业务逻辑
+- 使用异步处理
+
+**慢查询优化：**
+- 添加数据库索引
+- 优化 SQL 查询
+- 减少 N+1 查询
+
+**连接池优化：**
+- 调整 `maxconn` 配置
+- 检查连接泄漏
+- 优化连接复用
+
+---
+
+## 📊 监控最佳实践
+
+### 1. 设置告警
+
+```python
+# 慢请求告警
+if process_time > 1.0:
+    send_alert(f"Slow request: {request.url}")
+
+# 错误率告警
+if error_rate > 0.05:  # 5%
+    send_alert(f"High error rate: {error_rate}")
+```
+
+### 2. 定期审查
+
+- 每日检查慢请求日志
+- 每周审查性能趋势
+- 每月优化瓶颈
+
+### 3. 压力测试
+
+```bash
+# 使用 Apache Bench
+ab -n 1000 -c 10 http://localhost:8000/api/v1/workspaces
+
+# 使用 wrk
+wrk -t4 -c100 -d30s http://localhost:8000/api/v1/workspaces
+```
+
+---
+
+## 🎯 性能目标
+
+| 指标 | 目标 | 优秀 |
+|------|------|------|
+| API 平均响应时间 | <200ms | <50ms |
+| 数据库查询平均时间 | <50ms | <10ms |
+| 慢请求比例 | <5% | <1% |
+| 错误率 | <1% | <0.1% |
+| 连接池使用率 | <80% | <60% |
+
+---
+
+## 🔗 相关工具
+
+**APM 工具（推荐）：**
+- New Relic
+- Datadog
+- Sentry
+
+**开源方案：**
+- Prometheus + Grafana
+- ELK Stack
+- Jaeger (分布式追踪)
+
+---
+
+**最后更新:** 2026-06-17