5.4. Profiling memory usage

In addition to profiling the time and allocation behaviour of your program, you can also generate a graph of its memory usage over time. This is useful for detecting the causes of space leaks, when your program holds on to more memory at run-time that it needs to. Space leaks lead to longer run-times due to heavy garbage collector ativity, and may even cause the program to run out of memory altogether.

To generate a heap profile from your program:

Compile the program for profiling (Section 5.2).
Run it with one of the heap profiling options described below (eg. -hc for a basic producer profile). This generates the file prog.hp.
Run hp2ps to produce a Postscript file, prog.ps. The hp2ps utility is described in detail in Section 5.6.
Display the heap profile using a postscript viewer such as Ghostview, or print it out on a Postscript-capable printer.

5.4.1. RTS options for heap profiling

There are several different kinds of heap profile that can be generated. All the different profile types yield a graph of live heap against time, but they differ in how the live heap is broken down into bands. The following RTS options select which break-down to use:

-hc: Breaks down the graph by the cost-centre stack which produced the data.
-hm: Break down the live heap by the module containing the code which produced the data.
-hd: Breaks down the graph by closure description. For actual data, the description is just the constructor name, for other closures it is a compiler-generated string identifying the closure.
-hy: Breaks down the graph by type. For closures which have function type or unknown/polymorphic type, the string will represent an approximation to the actual type.
-hr: Break down the graph by retainer set. Retainer profiling is described in more detail below (Section 5.4.2).
-hb: Break down the graph by biography. Biographical profiling is described in more detail below (Section 5.4.3).

In addition, the profile can be restricted to heap data which satisfies certain criteria - for example, you might want to display a profile by type but only for data produced by a certain module, or a profile by retainer for a certain type of data. Restrictions are specified as follows:

-hcname,...: Restrict the profile to closures produced by cost-centre stacks with one of the specified cost centres at the top.
-hCname,...: Restrict the profile to closures produced by cost-centre stacks with one of the specified cost centres anywhere in the stack.
-hmmodule,...: Restrict the profile to closures produced by the specified modules.
-hddesc,...: Restrict the profile to closures with the specified description strings.
-hytype,...: Restrict the profile to closures with the specified types.
-hrcc,...: Restrict the profile to closures with retainer sets containing cost-centre stacks with one of the specified cost centres at the top.
-hbbio,...: Restrict the profile to closures with one of the specified biographies, where bio is one of lag, drag, void, or use.

For example, the following options will generate a retainer profile restricted to Branch and Leaf constructors:

prog +RTS -hr -hdBranch,Leaf

There can only be one "break-down" option (eg. -hr in the example above), but there is no limit on the number of further restrictions that may be applied. All the options may be combined, with one exception: GHC doesn't currently support mixing the -hr and -hb options.

There's one more option which relates to heap profiling:

-isecs:: Set the profiling (sampling) interval to secs seconds (the default is 0.1 second). Fractions are allowed: for example -i0.2 will get 5 samples per second. This only affects heap profiling; time profiles are always sampled on a 1/50 second frequency.

5.4.2. Retainer Profiling

Retainer profiling is designed to help answer questions like "why is this data being retained?". We start by defining what we mean by a retainer:

A retainer is either the system stack, or an unevaluated closure (thunk).

In particular, constructors are not retainers.

An object A is retained by an object B if object A can be reached by recursively following pointers starting from object B but not meeting any other retainers on the way. Each object has one or more retainers, collectively called its retainer set.

When retainer profiling is requested by giving the program the -hr option, a graph is generated which is broken down by retainer set. A retainer set is displayed as a set of cost-centre stacks; because this is usually too large to fit on the profile graph, each retainer set is numbered and shown abbreviated on the graph along with its number, and the full list of retainer sets is dumped into the file prog.prof.

Retainer profiling requires multiple passes over the live heap in order to discover the full retainer set for each object, which can be quite slow. So we set a limit on the maximum size of a retainer set, where all retainer sets larger than the maximum retainer set size are replaced by the special set MANY. The maximum set size defaults to 8 and can be altered with the -R RTS option:

-Rsize: Restrict the number of elements in a retainer set to size (default 8).

5.4.2.1. Hints for using retainer profiling

The definition of retainers is designed to reflect a common cause of space leaks: a large structure is retained by an unevaluated computation, and will be released once the compuation is forced. A good example is looking up a value in a finite map, where unless the lookup is forced in a timely manner the unevaluated lookup will cause the whole mapping to be retained. These kind of space leaks can often be eliminated by forcing the relevant computations to be performed eagerly, using seq or strictness annotations on data constructor fields.

Often a particular data structure is being retained by a chain of unevaluated closures, only the nearest of which will be reported by retainer profiling - for example A retains B, B retains C, and C retains a large structure. There might be a large number of Bs but only a single A, so A is really the one we're interested in eliminating. However, retainer profiling will in this case report B as the retainer of the large structure. To move further up the chain of retainers, we can ask for another retainer profile but this time restrict the profile to B objects, so we get a profile of the retainers of B:

prog +RTS -hr -hcB

This trick isn't foolproof, because there might be other B closures in the heap which aren't the retainers we are interested in, but we've found this to be a useful technique in most cases.

5.4.3. Biographical Profiling

A typical heap object may be in one of the following four states at each point in its lifetime:

The lag stage, which is the time between creation and the first use of the object,
the use stage, which lasts from the first use until the last use of the object, and
The drag stage, which lasts from the final use until the last reference to the object is dropped.
An object which is never used is said to be in the void state for its whole lifetime.

A biographical heap profile displays the portion of the live heap in each of the four states listed above. Usually the most interesting states are the void and drag states: live heap in these states is more likely to be wasted space than heap in the lag or use states.

It is also possible to break down the heap in one or more of these states by a different criteria, by restricting a profile by biography. For example, to show the portion of the heap in the drag or void state by producer:

prog +RTS -hc -hbdrag,void

Once you know the producer or the type of the heap in the drag or void states, the next step is usually to find the retainer(s):

prog +RTS -hr -hccc...

NOTE: this two stage process is required because GHC cannot currently profile using both biographical and retainer information simultaneously.