ghc/docs/users_guide/prof-post-processors.lit

   1 %
   2 % Included by  prof-options.lit
   3 %
   4
   5 Utility programs which produce graphical profiles.
   6
   7 \subsubsection[hp2ps]{\tr{hp2ps}--heap profile to PostScript}
   8 \index{hp2ps (utility)}
   9 \index{heap profiles}
  10 \index{PostScript, from heap profiles}
  11
  12 %\vspace{2ex}
  13 %\begin{quote}
  14 USAGE: \tr{hp2ps} [flags] [\pl{<file>}[\tr{.stat}]]
  15 %\end{quote}
  16
  17 The program \tr{hp2ps}\index{hp2ps} converts a heap profile as
  18 produced by the \tr{-h<break-down>}\index{-h<break-down> RTS option}
  19 runtime option into a PostScript graph of the heap profile. By
  20 convention, the file to be processed by \tr{hp2ps} has a \tr{.hp}
  21 extension. The PostScript output is written to \pl{<file>}\tr{.ps}. If
  22 \pl{<file>} is omitted entirely, then the program behaves as a filter.
  23
  24 \tr{hp2ps} is distributed in \tr{ghc/utils/hp2ps}. It was originally
  25 developed by Dave Wakeling as part of the HBC/LML heap
  26 profiler.
  27
  28
  29 The flags are:
  30 \begin{description}
  31 \item[\tr{-d}]
  32 In order to make graphs more readable, \tr{hp2ps} sorts the shaded
  33 bands for each identifier. The default sort ordering is for the bands
  34 with the largest area to be stacked on top of the smaller ones.  The
  35 \tr{-d} option causes rougher bands (those representing series of
  36 values with the largest standard deviations) to be stacked on top of
  37 smoother ones.
  38
  39 \item[\tr{-b}]
  40 Normally, \tr{hp2ps} puts the title of the graph in a small box at the
  41 top of the page. However, if the JOB string is too long to fit in a
  42 small box (more than 35 characters), then
  43 \tr{hp2ps} will choose to use a big box instead.  The \tr{-b}
  44 option forces \tr{hp2ps} to use a big box.
  45
  46 \item[\tr{-e<float>[in|mm|pt]}]
  47 Generate encapsulated PostScript suitable for inclusion in LaTeX
  48 documents.  Usually, the PostScript graph is drawn in landscape mode
  49 in an area 9 inches wide by 6 inches high, and \tr{hp2ps} arranges
  50 for this area to be approximately centred on a sheet of a4 paper.
  51 This format is convenient of studying the graph in detail, but it is
  52 unsuitable for inclusion in LaTeX documents.  The \tr{-e} option
  53 causes the graph to be drawn in portrait mode, with float specifying
  54 the width in inches, millimetres or points (the default).  The
  55 resulting PostScript file conforms to the Encapsulated PostScript
  56 (EPS) convention, and it can be included in a LaTeX document using
  57 Rokicki's dvi-to-PostScript converter \tr{dvips}.
  58
  59 \item[\tr{-g}]
  60 Create output suitable for the \tr{gs} PostScript previewer (or
  61 similar). In this case the graph is printed in portrait mode without
  62 scaling. The output is unsuitable for a laser printer.
  63
  64 \item[\tr{-l}]
  65 Normally a profile is limited to 20 bands with additional identifiers
  66 being grouped into an \tr{OTHER} band. The \tr{-l} flag removes this
  67 20 band and limit, producing as many bands as necessary. No key is
  68 produced as it won't fit!. It is useful for creation time profiles
  69 with many bands.
  70
  71 \item[\tr{-m<int>}]
  72 Normally a profile is limited to 20 bands with additional identifiers
  73 being grouped into an \tr{OTHER} band. The \tr{-m} flag specifies an
  74 alternative band limit (the maximum is 20).
  75
  76 \tr{-m0} requests the band limit to be removed. As many bands as
  77 necessary are produced. However no key is produced as it won't fit! It
  78 is useful for displaying creation time profiles with many bands.
  79
  80 \item[\tr{-p}]
  81 Use previous parameters. By default, the PostScript graph is
  82 automatically scaled both horizontally and vertically so that it fills
  83 the page.  However, when preparing a series of graphs for use in a
  84 presentation, it is often useful to draw a new graph using the same
  85 scale, shading and ordering as a previous one. The \tr{-p} flag causes
  86 the graph to be drawn using the parameters determined by a previous
  87 run of \tr{hp2ps} on \pl{file}. These are extracted from
  88 \pl{file}\tr{.aux}.
  89
  90 \item[\tr{-s}] Use a small box for the title.
  91
  92 \item[\tr{-t<float>}]
  93 Normally trace elements which sum to a total of less than 1\% of the
  94 profile are removed from the profile. The \tr{-t} option allows this
  95 percentage to be modified (maximum 5\%).
  96
  97 \tr{-t0} requests no trace elements to be removed from the profile,
  98 ensuring that all the data will be displayed.
  99
 100 \item[\tr{-?}] Print out usage information.
 101 \end{description}
 102
 103 \subsubsection[stat2resid]{\tr{stat2resid}---residency info from GC stats}
 104 \index{stat2resid (utility)}
 105 \index{GC stats---residency info}
 106 \index{residency, from GC stats}
 107
 108 %\vspace{2ex}
 109 %\begin{quote}
 110 USAGE: \tr{stat2resid} [\pl{<file>}[\tr{.stat}] [\pl{<outfile>}]]
 111 %\end{quote}
 112
 113 The program \tr{stat2resid}\index{stat2resid} converts a detailed
 114 garbage collection statistics file produced by the
 115 \tr{-S}\index{-S RTS option} runtime option into a PostScript heap
 116 residency graph. The garbage collection statistics file can be
 117 produced without compiling your program for profiling.
 118
 119 By convention, the file to be processed by \tr{stat2resid} has a
 120 \tr{.stat} extension. If the \pl{<outfile>} is not specified the
 121 PostScript will be written to \pl{<file>}\tr{.resid.ps}. If
 122 \pl{<file>} is omitted entirely, then the program behaves as a filter.
 123
 124 The plot can not be produced from the statistics file for a
 125 generational collector, though a suitable stats file can be produced
 126 using the \tr{-F2s}\index{-F2s RTS option} runtime option when the
 127 program has been compiled for generational garbage collection (the
 128 default).
 129
 130 \tr{stat2resid} is distributed in \tr{ghc/utils/stat2resid}.