关于 gprof2dot

这是一个Python脚本，用于将多种性能分析器的输出转换为dot图。

它可以：

• 读取以下工具的输出：
  • Linux perf
  • Valgrind的callgrind工具
  • OProfile
  • Sysprof
  • Xperf
  • VTune
  • Very Sleepy
  • Python分析器
  • Java的HPROF
  • prof, gprof
  • DTrace
  • FlameGraph的stackcollapse
• 裁剪低于某个阈值的节点和边；
• 使用启发式方法在互递归函数中传播时间；
• 有效利用颜色来突出热点；
• 可在任何安装了Python和Graphviz的平台上运行，即几乎任何地方；
• 比较两个结构几乎相同的图表，用于分析时间或函数调用等性能指标。

如果你想要一个用于查看_gprof2dot_生成的图表的交互式查看器，请查看xdot.py。

状态

_gprof2dot_目前满足了我的需求，我几乎没有时间维护它。所以恐怕任何功能请求都不太可能被实现，我处理问题报告或拉取请求的速度可能会很慢。

示例

这是使用默认设置处理Linux Gazette文章中的示例数据得到的结果：

要求

• Python：已知可与版本>=3.8一起使用；很可能_不_适用于更早的版本。
• Graphviz：已测试2.26.3版本，但应该可以与其他版本一起使用。

Windows用户

• 下载并安装Python for Windows
• 下载并安装Graphviz for Windows

Linux用户

在Debian/Ubuntu上运行：

apt-get install python3 graphviz

在RedHat/Fedora上运行：

yum install python3 graphviz

下载

• PyPI

  pip install gprof2dot
  

• 独立脚本

• Git仓库

文档

使用方法

用法：
	gprof2dot.py [选项] [文件] ...
选项:
  -h, --help            显示此帮助信息并退出
  -o FILE, --output=FILE
                        输出文件名 [标准输出]
  -n PERCENTAGE, --node-thres=PERCENTAGE
                        消除低于此阈值的节点 [默认: 0.5]
  -e PERCENTAGE, --edge-thres=PERCENTAGE
                        消除低于此阈值的边 [默认: 0.1]
  -f FORMAT, --format=FORMAT
                        配置文件格式: axe, callgrind, collapse, dtrace,
                        hprof, json, oprofile, perf, prof, pstats, sleepy,
                        sysprof 或 xperf [默认: prof]
  --total=TOTALMETHOD   计算总时间的首选方法: callratios
                        或 callstacks (当前仅影响 perf 格式)
                        [默认: callratios]
  -c THEME, --colormap=THEME
                        颜色映射: bw, color, gray, pink 或 print [默认:
                        color]
  -s, --strip           从解析后的 C++ 函数名中去除函数参数、模板参数和
                        const 修饰符
  --color-nodes-by-selftime
                        根据自身时间而非总时间(自身时间和后代时间之和)
                        为节点着色
  -w, --wrap            换行函数名
  --show-samples        显示函数样本
  --node-label=MEASURE  在节点上显示的测量值(可多次指定): self-time, self-time-percentage,
                        total-time 或 total-time-percentage [默认: total-
                        time-percentage, self-time-percentage]
  --list-functions=LIST_FUNCTIONS
                        列出可用于在 -z 或 -l 中选择的函数,
                        需要选择器参数(使用 '+' 选择全部)。
                        请记住,选择器参数使用 Unix/Bash 通配符/模式匹配,
                        条目格式为 '<pkg>:<linenum>:<function>'。当
                        参数以 '%' 开头时,将对选定条目执行所有可用
                        信息的转储,删除前导 '%'。
  -z ROOT, --root=ROOT  修剪调用图以仅显示指定根函数的后代
  -l LEAF, --leaf=LEAF  修剪调用图以仅显示指定叶函数的祖先
  --depth=DEPTH         修剪调用图以仅显示指定深度的后代或祖先
  --skew=THEME_SKEW     倾斜着色曲线。值 < 1.0 为较低百分比提供更多
                        变化。值 > 1.0 为较低百分比提供较少变化
  -p FILTER_PATHS, --path=FILTER_PATHS
                       过滤不在指定路径中的所有模块
  --compare             比较两个结构几乎相同的图。使用此
                        选项时应提供两个文件。gprof2dot.py
                        [选项] --compare [文件1] [文件2] ...
  --compare-tolerance=TOLERANCE
                        节点差异的容差阈值
                        (默认为0.001%)。如果差异低于此值,
                        则认为节点相同。
  --compare-only-slower
                        仅显示第二个图中较慢函数的比较。
  --compare-only-faster
                        仅显示第二个图中较快函数的比较。
  --compare-color-by-difference
                        基于差异值为节点着色。
                        差异最大的节点表示热点。

示例

Linux perf

    perf record -g -- /path/to/your/executable
    perf script | c++filt | gprof2dot.py -f perf | dot -Tpng -o output.png

oprofile

    opcontrol --callgraph=16
    opcontrol --start
    /path/to/your/executable arg1 arg2
    opcontrol --stop
    opcontrol --dump
    opreport -cgf | gprof2dot.py -f oprofile | dot -Tpng -o output.png

xperf

如果你不熟悉 xperf,请先阅读[这篇excellent文章](https://blogs.msdn.com/b/pigscanfly/archive/2009/08/06/stack-walking-in-xperf.aspx)。然后执行:

  * 启动 xperf:

        xperf -on Latency -stackwalk profile

  * 运行你的应用程序。

  * 保存数据:

        xperf -d output.etl

  * 启动可视化工具:

        xperf output.etl

  * 在 _Trace_ 菜单中,选择 _Load Symbols_。如有必要,_Configure Symbol Paths_。

  * 在 _CPU sampling graph_ 上选择感兴趣的区域,右键单击,选择 _Summary Table_。

  * 在 _Columns_ 菜单中,确保启用并显示 _Stack_ 列。

  * 右键单击一行,选择 _Export Full Table_,保存为 _output.csv_。

  * 然后调用 gprof2dot:

        gprof2dot.py -f xperf output.csv | dot -Tpng -o output.png

VTune Amplifier XE

  * 收集配置文件数据(也可以从 GUI 完成):

        amplxe-cl -collect hotspots -result-dir output -- your-app

  * 可视化配置文件数据:

        amplxe-cl -report gprof-cc -result-dir output -format text -report-output output.txt
        gprof2dot.py -f axe output.txt | dot -Tpng -o output.png

另请参阅 [Kirill Rogozhin 的博客文章](http://web.archive.org/web/20130506045856/http://software.intel.com:80/en-us/blogs/2013/04/05/making-visualized-call-graph-from-intel-vtune-amplifier-xe-results)。

gprof

    /path/to/your/executable arg1 arg2
    gprof path/to/your/executable | gprof2dot.py | dot -Tpng -o output.png

python profile

    python -m profile -o output.pstats path/to/your/script arg1 arg2
    gprof2dot.py -f pstats output.pstats | dot -Tpng -o output.png

python cProfile (以前称为 lsprof)

    python -m cProfile -o output.pstats path/to/your/script arg1 arg2
    gprof2dot.py -f pstats output.pstats | dot -Tpng -o output.png

Java HPROF

    java -agentlib:hprof=cpu=samples ...
    gprof2dot.py -f hprof java.hprof.txt | dot -Tpng -o output.png

详情请参阅 [Russell Power 的博客文章](http://web.archive.org/web/20220122110828/http://rjp.io/2012/07/03/java-profiling/)。

DTrace

    dtrace -x ustackframes=100 -n 'profile-97 /pid == 12345/ { @[ustack()] = count(); } tick-60s { exit(0); }' -o out.user_stacks
    gprof2dot.py -f dtrace out.user_stacks | dot -Tpng -o output.png
# 注意:有时dtrace的输出格式可能是latin-1,这会导致gprof2dot无法解析。
# 要解决这个问题,你应该使用iconv显式转换为UTF-8。
# TODO:添加一个编码标志来告诉gprof2dot如何解码profile文件。
iconv -f ISO-8859-1 -t UTF-8 out.user_stacks | gprof2dot.py -f dtrace

### stackcollapse

Brendan Gregg的FlameGraph工具以包含每个样本一行的文本文件作为输入。这种格式可以通过使用[FlameGraph仓库](https://github.com/brendangregg/FlameGraph)中的`stackcollapse`脚本从各种其他输入生成。它也可以由[py-spy](https://github.com/benfred/py-spy)等工具生成。

使用示例:

  * Perf

        perf record -g -- /path/to/your/executable
        perf script | FlameGraph/stackcollapse-perf.pl > out.collapse
        gprof2dot.py -f collapse out.collapse | dot -Tpng -o output.png

  * Py-spy

        py-spy record -p <pidfile> -f raw -o out.collapse
        gprof2dot.py -f collapse out.collapse | dot -Tpng -o output.png

## 比较示例

此图展示了`--compare`和`--compare-color-by-difference`选项的使用示例。

![比较](https://yellow-cdn.veclightyear.com/ab5030c0/24eadb19-6e60-46b1-aaed-5c6c59cd7741.png)

指向右侧的箭头表示在第二个配置文件中函数表现更快,而指向左侧的箭头表示在第一个配置文件中函数更快。

### 节点

    +-----------------------------+
    |        函数名                 \
    | 总时间%  -/+ 总差异             \
    | (自身时间%) -/+ 自身差异         /
    | 总调用次数1 / 总调用次数2        /
    +-----------------------------+

其中
- `总时间%`和`自身时间%`来自第一个配置文件
- `差异`计算为`第一个配置文件中的时间 - 第二个配置文件中的时间`的绝对值。

> **注意** 比较选项已经在pstats、axe和callgrind配置文件上进行了测试。

## 输出

输出图中的节点代表一个函数,具有以下布局:

    +------------------------------+
    |           函数名              |
    |  总时间% (自身时间%)           |
    |         总调用次数             |
    +------------------------------+

其中:

  * _总时间%_ 是在此函数及其所有子函数中花费的运行时间百分比;
  * _自身时间%_ 是仅在此函数本身花费的运行时间百分比;
  * _总调用次数_ 是此函数被调用的总次数(包括递归调用)。

边表示两个函数之间的调用,具有以下布局:

               总时间%
               调用次数
    父函数 --------------------> 子函数

其中:

  * _总时间%_ 是从子函数转移到这个父函数的运行时间百分比(如果可用);
  * _调用次数_ 是父函数调用子函数的次数。

注意,在递归循环中,节点中的_总时间%_对循环中的所有函数都是相同的,并且循环内的边上没有_总时间%_数字,因为这样的数字没有意义。

节点和边的颜色根据_总时间%_值变化。在默认的_类温度_色图中,花费最多时间的函数(热点)标记为饱和红色,花费较少时间的函数标记为深蓝色。请注意,默认情况下,花费很少或没有时间的函数不会出现在图中。

## 列出函数

`--list-functions`标志允许列出在`gprof`输入中找到的函数条目。
这旨在为使用`--leaf`(`-l`)或`--root`(`-z`)标志做准备。

  ~~~
  prof2dot.py -f pstats /tmp/myLog.profile  --list-functions "test_segments:*:*" 
    
  test_segments:5:<module>,
  test_segments:206:TestSegments,
  test_segments:46:<lambda>
  ~~~

  - 选择器参数使用Unix/Bash通配符/模式匹配,方式与`-l`和`-z`标志相同。
	  
  - 条目格式为'\<包\>:\<行号\>:\<函数\>'。
	
  - 当选择器参数以'%'开头时,会在删除选择器前导'%'后,为选定条目执行所有可用信息的转储。如果选择器是"+"或"*",则打印完整的函数列表。

## 常见问题

### 如何生成完整的调用图?

默认情况下,`gprof2dot.py`生成_部分_调用图,排除了对总计算时间影响很小或没有影响的节点和边。如果你想要完整的调用图,则通过`-n` / `--node-thres`和`-e` / `--edge-thres`选项将节点和边的阈值设置为零,如:

    gprof2dot.py -n0 -e0

### 节点标签太宽了。如何缩小它们?

当分析C++代码时,由于包含作用域、函数参数和模板参数在解码后的C++函数名中,节点标签可能会变得非常宽。

如果你不需要函数和模板参数信息,那么使用`-s` / `--strip`选项来去除它们。

如果你想保留所有这些信息,或者标签仍然太宽,那么你可以使用`-w` / `--wrap`来换行标签。请注意,因为`dot`不会自动换行标签,所以标签边距不会完全对齐。

### 为什么没有输出,或者全都是同一种颜色?

很可能总执行时间太短,因此配置文件中没有足够的精度来确定时间花在哪里。

你仍然可以通过`-n` / `--node-thres`和`-e` / `--edge-thres`选项将节点和边的阈值设置为零来强制显示整个图,如:

    gprof2dot.py -n0 -e0

但要获得有意义的结果,你需要找到一种方法来延长程序的运行时间(汇总多次运行的结果)。

### 为什么百分比加起来不对?

你可能的执行时间太短,导致舍入误差很大。

请参阅上面的问题,了解如何增加执行时间的方法。

### 在编译用于分析时,我应该向gcc传递哪些选项?

产生合适结果的_必要_选项有:

  * **`-g`** : 生成调试信息
  * **`-fno-omit-frame-pointer`** : 使用帧指针(在一些架构如x86_64和某些优化级别中,默认禁用帧指针使用;没有它就无法遍历调用栈)
如果你使用gprof，你还需要`-pg`选项，但现在你可以使用其他分析工具获得更好的结果，其中大多数工具在编译时不需要特殊的代码插桩。

你希望分析的代码尽可能接近你将要发布的代码。因此，你应该包括所有在发布代码中使用的选项，通常包括：

  * **`-O2`**：不涉及空间-速度权衡的优化
  * **`-DNDEBUG`**：禁用标准库中的调试代码（如assert宏）

然而，gcc执行的许多优化会影响分析结果的准确性/粒度。你应该传递这些选项来禁用那些特定的优化：

  * **`-fno-inline-functions`**：不要将函数内联到其父函数中（否则这些函数花费的时间将被归属于调用者）
  * **`-fno-inline-functions-called-once`**：与上面类似
  * **`-fno-optimize-sibling-calls`**：不要优化兄弟和尾递归调用（否则尾调用可能被归属于父函数）

如果粒度仍然太低，你可以传递这些选项以获得更细的粒度：

  * **`-fno-default-inline`**：不要仅仅因为成员函数在类作用域内定义就默认将其内联
  * **`-fno-inline`**：不要理会inline关键字

但请注意，使用这些最后的选项，被多次调用的函数的计时将因函数调用开销而失真。这对于典型的C++代码尤其如此，因为它期望这些优化能为decent性能而完成。

有关更多信息，请参阅[gcc优化选项完整列表](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html)。

# 链接

查看[wiki](https://github.com/jrfonseca/gprof2dot/wiki)获取外部资源，包括补充/替代工具。