Callgrind

From Apache OpenOffice Wiki
Jump to: navigation, search

Callgrind (also known under the names Calltree and Cachegrind) is a call graph profiler (performance profiling tool) that runs on Linux x86. It builds on the Valgrind framework and has a graphical KDE frontend, KCachegrind.

The Valgrind user manual has a chapter of documentation. More documentation is available at KCachegrind, especially see the usage examples.

Installing

GraphViz is needed to see graphical call trees in KCachegrind.

Debian

aptitude install valgrind kcachegrind graphviz

Stock Debian/Etch has Valgrind 3.2.1, KCachegrind 3.5.5 and GraphViz 2.8

Debian/Lenny has Valgrind 3.3.1, KCachegrind 3.5.9 and GraphViz 2.20.2

(K)Ubuntu

aptitude install valgrind kcachegrind graphviz

Hardy has Valgrind 3.3.0, KCachegrind 0.x?kde (KDE 3.5.10) and GraphViz 2.16

Jaunty has Valgrind 3.4.1, KCachegrind 0.5.0kde (KDE 4.2.2) and GraphViz 2.20.2

SuSE / openSUSE

SuSE 9.2

On SuSE 9.2, just install the kdesdk3-profile package (which will also install the valgrind package as a dependency). To see call graphs in kcachegrind, you also need to install the graphviz package.

Doing so installs Callgrind version 0.9.8, Valgrind version 2.2.0, and KCachegrind version 0.4.5kde on your machine.

Useful documentation is locally installed at /usr/share/doc/packages/valgrind/ct_main.html.

openSUSE 11.2

On openSUSE 11.2, you need to install the valgrind and kcachegrind packages to get callgrind and kcachegrind installed. There is no separate package for callgrind, as the valgrind packages provides callgrind.

As root, just run

  zypper in valgrind kcachegrind graphviz

to install the necessary packages.

Profiling OpenOffice.org

To profile a run from startup to end and see which methods are involved with the amount of calls and time spent, a simple

valgrind --tool=callgrind ./soffice.bin

in openoffice.org3/program would be sufficient.

No extra instrumentation of the executable is needed for general call graph profiling. However, to gather data down to the source code level, debug (line number) information is needed for the module(s) of interest. Use a product build. Do not use the debug=true argument to build or dmake, as it would alter optimization or entirely switch it off. Instead, use ENVCFLAGS+=-g. The procedure to rebuild a module such would be

cd module
rm unxlngi6.pro/slo/*
build -- ENVCFLAGS+=-g

and copy the resulting libraries to the openoffice.org/basis3.0/program directory.

To repeatedly profile some usage scenario, best

cd openoffice.org3/program
cp soffice soffice_callgrind

edit soffice_callgrind and change the line reading "$sd_prog/$sd_binary" "$@" &

valgrind --tool=callgrind --separate-threads=yes --instr-atstart=no "$sd_prog/soffice.bin" "$@" &

Start the office with

./soffice_callgrind

To start instrumentation and collect data at some point use the command

callgrind_control -i on

To dump the data collected and stop instrumentation use

callgrind_control -d
callgrind_control -i off

If callgrind_control complains it can't find the active callgrind run, either use option -w with the working directory as instructed, or use the callgrind.cmd method:

echo +Instrumentation > callgrind.cmd
# ... profile task ...
echo Dump > callgrind.cmd
echo -Instrumentation >> callgrind.cmd

You will find a file callgrind.out.pid and several callgrind.out.pid.thread files in the directory. To inspect the call graph enter

kcachegrind callgrind.out.pid

On the first run of KCachegrind, to be able to see the corresponding source code, you will need to tell KCachegrind the location of the source code directories for a specific library. This is the most cumbersome part. Go to Settings → Configure KCachegrind → Annotations and scroll to the desired library. Click Add and click your way through until you reach the proper source directory. Repeat for other directories needed. [ed: is there really no easier way than all this clicking-around?]

Now dive into the graphs, read the documentation mentioned above when not sure what to do.


old how-to, for reference

Documentation note.png Copied blatantly from http://tools.openoffice.org/profiling/callgrind-howto.html dated 2005-01-12, with almost no semantical edits, so needs updating..

e.g., the callgrind utility in newer versions is a subtool invoked with valgrind --tool=callgrind instead.
The original author of this how-to is Stephan Bergmann.


No modification or instrumentation is necessary for profiling a sufficiently recent soffice.bin (I successfully tested this with OpenOffice.org 1.9.71). In the OpenOffice.org program directory, just execute

callgrind ./soffice.bin

When executing Java or some legacy dynamic libraries within soffice.bin, remember to extend LD_LIBRARY_PATH with the output of javaldx or with the OpenOffice.org program directory, respectively.

When callgrind is finished, it writes a file callgrind.out.pid. Use

kcachegrind callgrind.out.pid

to view it. I experienced the problem that the generated file is very small (around 500 byte) and does not contain the necessary information when profiling soffice.bin. In that case, it worked for me to execute

callgrind --separate-threads=yes ./soffice.bin

instead, which writes out individual files callgrind.out.pid.thread together with an empty callgrind.out.pid. Opening that empty callgrind.out.pid in kcachegrind automatically reads in all the individual thread files.

Detailed information at the source/assembler instruction level can be gathered by specifying the additional callgrind options --dump-instr=yes and --trace-jump=yes.


Limitations

It worked fine for me to profile soffice.bin, just starting it up and immediately closing it again with Ctrl-Q, and to similarly profile soffice.bin -swriter. However, callgrind easily runs out of memory when gathering data for longer runs, or runs in which more dynamic libraries are loaded.

One solution to this problem might be to only gather data for parts of an soffice.bin run, using the --instr-atstart and --collect-atstart options to callgrind, and using the callgrind_control tool (see the documentation). One caveat when using callgrind_control can be that it reports that no callgrind processes are running. In that case, it can work to manually place a callgrind.cmd file in the current working directory. That is, instead of

callgrind_control -i on

use

echo +Instrumentation > callgrind.cmd

and instead of

callgrind_control -d

use

echo Dump > callgrind.cmd

Using instrumentation only during operations that should be profiled also speeds up the startup of soffice.bin, so it is recommended to use this whenever the startup itself is not of interest.

Rather than using callgrind_control or callgrind.cmd, it is also possible to turn on and off instrumentation using macros within the source code itself. This is especially useful if callgrind fails to work without manually turning on and off instrumentation, or if the same code shall be profiled several times. The macro to turn instrumentation on is CALLGRIND_START_INSTRUMENTATION(), and the macro to turn it off is CALLGRIND_STOP_INSTRUMENTATION(). Both are contained in callgrind.h, which unfortunately is not installed with callgrind, but can be downloaded separately. callgrind.h includes valgrind.h, which is installed in /usr/include/valgrind already.

Personal tools