5.5. Runtime options for profiling

It isn't enough to compile your program for profiling with -prof!

When you run your profiled program, you must tell the runtime system (RTS) what you want to profile (e.g., time and/or space), and how you wish the collected data to be reported. You also may wish to set the sampling interval used in time profiling.

Executive summary: ./a.out +RTS -pT produces a time profile in a.out.prof; ./a.out +RTS -hC produces space-profiling info which can be mangled by hp2ps and viewed with ghostview (or equivalent).

Profiling runtime flags are passed to your program between the usual +RTS and -RTS options.

-p or -P:

The -p option produces a standard time profile report. It is written into the file <program>.prof.

The -P option produces a more detailed report containing the actual time and allocation data as well. (Not used much.)

-px:

The -px option generates profiling information in the XML format understood by our new profiling tool, see Section 5.3.

-i<secs>:

Set the profiling (sampling) interval to <secs> seconds (the default is 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.

-h<break-down>:

Produce a detailed heap profile of the heap occupied by live closures. The profile is written to the file <program>.hp from which a PostScript graph can be produced using hp2ps (see Section 5.6).

The heap space profile may be broken down by different criteria:

-hC:

cost centre which produced the closure (the default).

-hM:

cost centre module which produced the closure.

-hD:

closure description—a string describing the closure.

-hY:

closure type—a string describing the closure's type.

-h<filtering-options>:

It's often useful to select just some subset of the heap when profiling. To do this, the following filters are available. You may use multiple filters, in which case a closure has to satisfy all filters to appear in the final profile. Filtering criterion are independent of what it is you ask to see. So, for example, you can specify a profile by closure description (-hD) but ask to filter closures by producer module (-hm{...}).

Available filters are:

-hc{cc1, cc2 .. ccN}:

Restrict to one of the specified cost centers. Since GHC deals in cost center stacks, the specified cost centers pertain to the top stack element. For example, -hc{Wurble,Burble} selects all cost center stacks whose top element is Wurble or Burble.

-hm{module1, module2 .. moduleN}:

Restrict to closures produced by functions in one of the specified modules.

-hd{descr1, descr2 .. descrN}:

Restrict to closures whose description-string is one of the specified descriptions. Description strings are pretty arcane. An easy way to find plausible strings to specify is to first do a -hD profile and then inspect the description-strings which appear in the resulting profile.

-hy{type1, type2 .. typeN}:

Restrict to closures having one of the specified types.

-hx:

The -hx option generates heap profiling information in the XML format understood by our new profiling tool (NOTE: heap profiling with the new tool is not yet working! Use hp2ps-style heap profiling for the time being).

-xc

This option makes use of the extra information maintained by the cost-centre-stack profiler to provide useful information about the location of runtime errors. See Section 4.16.3.