| name | py-perf-analyzer |
| description | 定位 Python 脚本的性能瓶颈，集成 cProfile、tracemalloc 和 line_profiler，一键执行 CPU 热点函数、内存分配或逐行耗时分析，并可输出 JSON 报告。当用户提到优化脚本、分析性能、定位 CPU 或内存热点、进行逐行分析，或询问代码为什么慢、如何加速、内存泄漏等问题时触发。 |
| license | MIT |
| type | tool |
| tags | ["python","profiling","performance","cProfile","memory","optimization"] |
Perf Profiler
Python 性能分析工具，集成 cProfile、line_profiler 和 tracemalloc，一键定位 CPU 和内存瓶颈。
功能
- CPU 分析 (cProfile)：统计每个函数的调用次数、累计耗时、自身耗时，定位热点函数
- 内存分析 (tracemalloc)：追踪内存分配热点、峰值内存、内存增长来源
- 逐行分析 (line_profiler)：精确到每一行代码的耗时和命中次数，适合深入优化
- 组合分析：
all 模式一次执行同时收集 CPU + 内存数据，减少重复运行开销
依赖
| 依赖 | 类型 | 用途 |
|---|
| Python 3.7+ | 必须 | 运行环境 |
| cProfile / pstats | 内置 | CPU 性能分析 |
| tracemalloc | 内置 | 内存追踪 |
| line_profiler | 可选 | 逐行分析（pip install line_profiler） |
使用方式
python scripts/perf_profile.py <脚本路径> [脚本参数...] [选项]
参数
| 参数 | 说明 | 默认值 |
|---|
script | 要分析的 Python 脚本路径（必填） | - |
script_args | 传递给目标脚本的参数 | 无 |
--mode | 分析模式：cpu / memory / line / all | cpu |
--top | 显示 Top N 结果 | 20 |
--sort | CPU 分析排序：cumulative / tottime / calls | cumulative |
--output | 输出 JSON 报告到文件 | 仅终端输出 |
--function | 逐行分析的目标函数名（逗号分隔） | 自动发现 |
--threshold | 只显示占比超过此值(%)的函数 | 0 |
示例
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
python scripts/perf_profile.py my_script.py --mode all --top 10
python scripts/perf_profile.py my_script.py --output report.json -- --input data.csv --output result.csv
python scripts/perf_profile.py my_script.py --threshold 5
输出说明
CPU 分析报告
============================================================
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
内存分析报告
============================================================
内存分析报告 (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 报告
使用 --output 参数可导出完整的结构化 JSON 报告，包含所有分析维度的详细数据，便于后续处理或接入 CI 流水线。
