docs/dev/profiling.pod - Profiling Parrot


This file documents the use of Parrot's profiling runcore.


The profiling runcore is built as part of Parrot and is designed to allow discovery of bottlenecks in PIR code. It is also being instrumented to support HLL profiling, but this support is currently limited. Code can be run under the profiling runcore by passing -Rprofiling or --runcore profiling to the parrot binary. The location and format of the output file are determined by environment variables as documented below. If the profiling runcore does not detect any relevant environment variables, it will use the defaults described below.

Environment Variables

This determines the full name of the file where the output will be written, if any. Parrot does not check if the filename exists before opening it for writing and will happily overwrite any existing files, including previous profiles.If no value is specified, Parrot will write to a file named parrot.pprof.X, where X is the PID of the Parrot process. When the profiling runcore exits, it will print a message announcing where the profile was written.This variable can also have the special values stdout and stderr. When either of these values are detected (case-insensitively), Parrot will print its profiling output the stdout or stderr.
This determines the type of output which will contain the profile. Current options are pprof and none. pprof is the default and is a ascii-based human-readable format. It can be post-processed into a Callgrind-compatible format by tools/dev/ none writes nothing to the output file. It is most useful for testing and optimizing the profiling runcore itself. It is expected to be of little interest to users wishing to profile PIR and HLL code.
This determines whether PIR annotations will be recorded as part of the profile. Annotations are necessary when profiling HLL code, but will cause the profiling runcore to run more slowly. By default, they are disabled. Set this value to enable them.