py-perf-analyzer

name	py-perf-analyzer
description	定位 Python 脚本的性能瓶颈，集成 cProfile、tracemalloc 和 line_profiler，一键执行 CPU 热点函数、内存分配或逐行耗时分析，并可输出 JSON 报告。当用户提到优化脚本、分析性能、定位 CPU 或内存热点、进行逐行分析，或询问代码为什么慢、如何加速、内存泄漏等问题时触发。
license	MIT
metadata	{"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

示例

# 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

输出说明

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 流水线。