Add comprehensive memory analysis tool with guide and test script

Co-authored-by: jxxghp <jxxghp@163.com>
2026-07-12 16:02:35 +08:00 · 2025-07-09 08:04:10 +00:00
parent d17e85217b
commit 3efbd47ffd
3 changed files with 400 additions and 3 deletions
--- a/MEMORY_ANALYSIS_GUIDE.md
+++ b/MEMORY_ANALYSIS_GUIDE.md
@@ -0,0 +1,269 @@
+# 内存分析工具使用指南
+
+## 概述
+
+这个增强版的内存分析工具专门用于诊断Python应用程序的内存问题，特别是解决"总内存比各对象占比内存大很多"的问题。
+
+## 主要功能
+
+### 1. 系统级内存分析
+- 进程内存使用详情（RSS、VMS、共享内存等）
+- 系统内存状态
+- 内存映射分析
+
+### 2. Python对象深度分析
+- 对象类型统计（按内存大小排序）
+- Python对象总内存计算
+- 未统计内存识别
+
+### 3. 内存映射详细分析
+- 按权限分类的内存映射
+- 按文件分类的内存映射
+- 识别C扩展和系统库占用的内存
+
+### 4. 大对象分析
+- 识别大于1MB的对象
+- 对象详细信息（类型、大小、内容预览）
+
+### 5. 内存泄漏检测
+- tracemalloc内存分配统计
+- 内存分配最多的位置
+- 垃圾回收统计
+- 不可达对象检测
+
+## 使用方法
+
+### 基本使用
+
+```python
+from app.helper.memory import MemoryHelper
+
+# 创建内存分析器实例
+memory_helper = MemoryHelper()
+
+# 获取内存摘要
+summary = memory_helper.get_memory_summary()
+print(f"总内存: {summary['total_memory_mb']:.2f} MB")
+print(f"Python对象: {summary['python_objects_mb']:.2f} MB")
+print(f"未统计内存: {summary['unaccounted_mb']:.2f} MB")
+
+# 强制垃圾回收
+collected = memory_helper.force_garbage_collection()
+print(f"清理了 {collected} 个对象")
+
+# 创建详细分析报告
+analysis_file = memory_helper.create_detailed_memory_analysis()
+print(f"详细报告已保存到: {analysis_file}")
+```
+
+### 内存增长分析
+
+```python
+# 分析内存增长趋势（5分钟间隔）
+growth_info = memory_helper.analyze_memory_growth(300)
+print(f"内存增长率: {growth_info['growth_rate_mb_per_hour']:.2f} MB/小时")
+```
+
+### 启动自动监控
+
+```python
+# 启动内存监控（需要配置MEMORY_ANALYSIS=True）
+memory_helper.start_monitoring()
+
+# 停止监控
+memory_helper.stop_monitoring()
+```
+
+## 配置选项
+
+在配置文件中设置以下选项：
+
+```python
+# 启用内存分析
+MEMORY_ANALYSIS = True
+
+# 内存快照间隔（分钟）
+MEMORY_SNAPSHOT_INTERVAL = 5
+
+# 保留的快照文件数量
+MEMORY_SNAPSHOT_KEEP_COUNT = 30
+```
+
+## 输出文件
+
+### 1. 内存快照文件
+- 位置: `logs/memory_snapshots/memory_snapshot_YYYYMMDD_HHMMSS.txt`
+- 内容: 基本的内存使用统计
+
+### 2. 详细分析报告
+- 位置: `logs/memory_snapshots/detailed_memory_analysis_YYYYMMDD_HHMMSS.txt`
+- 内容: 完整的内存分析报告
+
+## 解决内存问题的步骤
+
+### 1. 识别未统计内存
+```python
+summary = memory_helper.get_memory_summary()
+if summary['unaccounted_percent'] > 50:
+    print("警告: 超过50%的内存未被Python对象统计")
+    print("可能的原因: C扩展、系统缓存、内存碎片")
+```
+
+### 2. 分析内存映射
+详细分析报告中的"内存映射详细分析"部分会显示：
+- 哪些文件占用了大量内存
+- 内存权限分布
+- 识别C扩展库
+
+### 3. 检测内存泄漏
+```python
+# 定期检查内存增长
+growth_info = memory_helper.analyze_memory_growth(300)
+if growth_info['growth_rate_mb_per_hour'] > 100:
+    print("警告: 内存增长过快，可能存在内存泄漏")
+```
+
+### 4. 分析大对象
+详细分析报告会列出所有大于1MB的对象，帮助识别：
+- 意外的内存占用
+- 缓存未清理
+- 数据结构过大
+
+## 常见问题解决
+
+### 问题1: 总内存比Python对象内存大很多
+
+**原因**: 
+- C扩展库占用内存
+- 系统缓存
+- 内存碎片
+- 共享库
+
+**解决方法**:
+1. 查看内存映射分析
+2. 检查是否有大量C扩展
+3. 分析系统级内存使用
+
+### 问题2: 内存持续增长
+
+**原因**:
+- 内存泄漏
+- 缓存未清理
+- 循环引用
+
+**解决方法**:
+1. 使用tracemalloc分析内存分配
+2. 检查垃圾回收统计
+3. 分析大对象列表
+
+### 问题3: 特定对象类型占用过多内存
+
+**解决方法**:
+1. 查看对象类型统计
+2. 分析大对象详情
+3. 检查对象引用关系
+
+## 性能注意事项
+
+1. **详细分析耗时**: `create_detailed_memory_analysis()` 可能需要几秒到几分钟
+2. **内存开销**: 分析过程本身会消耗一些内存
+3. **建议频率**: 不要过于频繁地运行详细分析，建议间隔5分钟以上
+
+## 调试技巧
+
+### 1. 在关键点添加内存检查
+```python
+def critical_function():
+    memory_helper = MemoryHelper()
+    before = memory_helper.get_memory_summary()
+    
+    # 执行关键操作
+    do_something()
+    
+    after = memory_helper.get_memory_summary()
+    growth = after['total_memory_mb'] - before['total_memory_mb']
+    if growth > 10:
+        print(f"警告: 函数执行后内存增长 {growth:.2f} MB")
+```
+
+### 2. 监控特定操作
+```python
+def monitor_operation(operation_name):
+    memory_helper = MemoryHelper()
+    before = memory_helper.get_memory_summary()
+    
+    # 执行操作
+    result = perform_operation()
+    
+    after = memory_helper.get_memory_summary()
+    growth = after['total_memory_mb'] - before['total_memory_mb']
+    
+    logger.info(f"{operation_name}: 内存增长 {growth:.2f} MB")
+    return result
+```
+
+## 示例输出
+
+### 内存摘要示例
+```
+total_memory_mb: 708.20
+python_objects_mb: 130.45
+unaccounted_mb: 577.75
+unaccounted_percent: 81.6
+```
+
+### 详细分析报告结构
+```
+详细内存分析报告 - 2025-07-09 14:26:00
+====================================================================================================
+
+1. 系统级内存分析
+--------------------------------------------------
+进程ID: 12345
+进程名称: python
+内存使用详情:
+  RSS (物理内存): 708.20 MB
+  VMS (虚拟内存): 1024.50 MB
+  共享内存: 45.30 MB
+  ...
+
+2. Python对象深度分析
+--------------------------------------------------
+总对象数: 1,234,567
+对象类型统计 (按内存大小排序):
+类型                 数量        总大小(MB)    平均大小(B)
+str                  318,537     34.56         113.5
+dict                 101,049     32.23         319.2
+...
+
+3. 内存映射详细分析
+--------------------------------------------------
+按权限分类的内存映射:
+权限        数量      大小(MB)
+r-xp        45        156.78
+rw-p        23        89.45
+...
+
+4. 大对象详细分析
+--------------------------------------------------
+大对象 (>1MB) 数量: 15
+
+ 1. dict - 45.67 MB
+    字典项数: 125000
+    示例键: ['user_data', 'cache', 'config']
+
+ 2. list - 23.45 MB
+    元素数量: 500000
+
+5. 内存泄漏检测
+--------------------------------------------------
+tracemalloc当前内存: 125.67 MB
+tracemalloc峰值内存: 145.23 MB
+
+内存分配最多的位置 (前15个):
+ 1.     1250 个对象,    45.67 MB
+    File "/app/core/cache.py", line 123
+    cache_data = load_large_dataset()
+```
+
+这个工具将帮助你全面了解应用程序的内存使用情况，特别是找出那些"消失"的内存去向。