= How to monitor and tune Gauche runtime and VM

In order to monitor and tune Gauche runtime and VM, we support to link
link:https://github.com/gperftools/gperftools[gperftools] to Gauche.

(NB: If you want to profile and tune Scheme programs, use Gauche's
profiling option instead.  See
link:http://practical-scheme.net/gauche/man/?l=en&p=Profiling%20and%20tuning[Profiling and tuning]
section of the manual.)


== Prerequisites

You need gperftools installed on your machine.  The source is available
in the above url.  On Debian/Ubuntu, you can get it with apt:

[source,console]
----
# apt-get install google-perftools libgoogle-perftools-dev
----


== Build:

To link gperftools, give `--with-gperftools` option to `./configure`:

[source,console]
----
$ ./configure --with-gperftools
----

Just linking gperftools doesn't affect much on runtime, but the behavior
of the program can be modified with environment variables, so we recommend
you not to use it for production releases.

Note that if you compile with this option, `SIGPROF` is reserved to
gperftools and not available for Scheme programs.


== Profile

When linked with gperftools, you can turn on CPU profiler by giving
a profile output filename to the environment variable `CPUPROFILE`.

[source,console]
----
$ env CPUPROFILE=prof.out gosh <arguments> ...
----

After `gosh` exits, profiling data is dumped to `prof.out` in the above
example.

Browsing the data is done by `pprof` tool.  Note that, on Ubuntu, it is
named `google-pprof` to avoid name conflict.

This shows call graph and sample analysis (replace `gosh` path appropriately):

[source,console]
----
$ pprof --gv /usr/local/bin/gosh prof.out
----

This shows samples per line, along the source code:

[source,console]
----
$ pprof --list=<function-name> gosh prof.out
----

And this shows samples per instruction:

[source,console]
----
$ pprof --disasm=<function-name> gosh prof.out
----

NB: Some versions of gperftools dumps the profiler output to a
file prof.out_{PID} where PID is the profiled process id.  If that's the
case, prof.out itself is empty.  Check the directory before referring
to the profiler output.
