Name
docs/dev/profiling.pod - Profiling Parrot
Description
This file documents the use of Parrot's profiling runcore.
Summary
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
PARROT_PROFILING_FILENAME
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_PROFILING_OUTPUT
This determines the type of output which will contain the profile.
Current options are PARROT_PROFILING_ANNOTATIONS
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.
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.
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/pprof2cg.pl.
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.