Python performance analysis tool, integrating cProfile, line_profiler, and tracemalloc, with one-click location of CPU and memory bottlenecks.
Features
- CPU analysis (cProfile): Counts each function's call count, cumulative time, and self time, locating hotspot functions
- Memory analysis (tracemalloc): Tracks memory allocation hotspots, peak memory, and sources of memory growth
- Line-by-line analysis (line_profiler): Time and hit count accurate to each line of code, suitable for in-depth optimization
- Combined analysis:
allmode executes once and collects CPU + memory data simultaneously, reducing the overhead of repeated runs
Dependencies
| Dependency | Type | Purpose |
|---|---|---|
| Python 3.7+ | Required | Runtime environment |
| cProfile / pstats | Built-in | CPU performance analysis |
| tracemalloc | Built-in | Memory tracking |
| line_profiler | Optional | Line-by-line analysis (pip install line_profiler) |
Usage
python scripts/perf_profile.py <脚本路径> [脚本参数...] [选项]
Parameters
| Parameter | Description | Default value |
|---|---|---|
script |
Path to the Python script to analyze (required) | - |
script_args |
Arguments passed to the target script | None |
--mode |
Analysis mode:cpu / memory / line / all |
cpu |
--top |
Show Top N results | 20 |
--sort |
CPU analysis sorting:cumulative / tottime / calls |
cumulative |
--output |
Output JSON report to file | Terminal output only |
--function |
Target function names for line-by-line analysis (comma-separated) | Auto-discover |
--threshold |
Only show functions whose percentage exceeds this value (%) | 0 |
Examples
# CPU 分析(默认模式)
python scripts/perf_profile.py my_script.py
# 内存分析
python scripts/perf_profile.py my_script.py --mode memory
# 逐行分析指定函数
python scripts/perf_profile.py my_script.py --mode line --function compute,process_data
# 全量分析(CPU + 内存),只看 Top 10
python scripts/perf_profile.py my_script.py --mode all --top 10
# 传递参数给目标脚本,输出 JSON 报告
python scripts/perf_profile.py my_script.py --output report.json -- --input data.csv --output result.csv
# 只关注占比 > 5% 的函数
python scripts/perf_profile.py my_script.py --threshold 5
Output description
CPU analysis report
============================================================
CPU 性能分析报告 (cProfile)
============================================================
总执行时间: 2.3456 秒
总函数调用: 1,234,567 次
分析函数数: 89 个
Top 5 耗时函数:
--------------------------------------------------------
排名 占比 累计(s) 自身(s) 调用 函数
--------------------------------------------------------
1 45.2% 1.0605 0.8234 1000 compute.py:23:matrix_multiply
2 22.1% 0.5183 0.5183 50000 utils.py:45:normalize
3 12.3% 0.2885 0.1200 500 io.py:12:read_batch
...
🔍 主要瓶颈: matrix_multiply (45.2% 时间)
位置: compute.py:23
Memory analysis report
============================================================
内存分析报告 (tracemalloc)
============================================================
峰值内存: 128.5 MB
当前内存: 64.2 MB
Top 5 内存分配:
--------------------------------------------------------
排名 大小 数量 位置
--------------------------------------------------------
1 45.2 MB 10000 data_loader.py:78
2 22.1 MB 5000 transform.py:45
...
内存增长热点:
--------------------------------------------------------
1 +32.0 MB (+8000) data_loader.py:78
...
JSON report
Use the --output parameter to export a complete structured JSON report, containing detailed data for all analysis dimensions, for subsequent processing or integration into a CI pipeline.