Skip to content

Commit

Permalink
Update the user guide with details on new flag +RTS -lu
Browse files Browse the repository at this point in the history 
It's for user events emitted from Haskell code, like traceEvent.
Fixes #5790
  • Loading branch information
@dcoutts
dcoutts committed Mar 22, 2012
1 parent ee8bf69 commit 050f714
Showing 1 changed file with 25 additions and 18 deletions.
43 changes: 25 additions & 18 deletions docs/users_guide/runtime_control.xml
View file
Expand Up @@ -1119,38 +1119,35 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
For some special use cases you may want more control over which
events are included. The <replaceable>flags</replaceable> is a
sequence of zero or more characters indicating which classes of
events to log. Currently there are four classes of events that can
events to log. Currently these the classes of events that can
be enabled/disabled:
<simplelist>
<member>
<option>s</option> &#8212; scheduler events, including Haskell
thread creation and start/stop events
thread creation and start/stop events. Enabled by default.
</member>
<member>
<option>g</option> &#8212; GC events, including GC start/stop
<option>g</option> &#8212; GC events, including GC start/stop.
Enabled by default.
</member>
<member>
<option>p</option> &#8212; parallel sparks (sampled)
<option>p</option> &#8212; parallel sparks (sampled).
Enabled by default.
</member>
<member>
<option>f</option> &#8212; parallel sparks (fully accurate)
<option>f</option> &#8212; parallel sparks (fully accurate).
Disabled by default.
</member>
<member>
<option>u</option> &#8212; user events. These are events emitted
from Haskell code using functions such as
<literal>Debug.Trace.traceEvent</literal>. Enabled by default.
</member>
</simplelist>
</para>

<para>
For spark events there are two modes: sampled and fully accurate.
There are various events in the life cycle of each spark, usually
just creating and running, but there are some more exceptional
possibilities. In the sampled mode the number of occurrences of each
kind of spark event is sampled at frequent intervals. In the fully
accurate mode every spark event is logged individually. The latter
has a higher runtime overhead and is not enabled by default.
</para>

<para>
The initial enabled event classes are 's', 'g' and 'p'. In addition
you can disable specific classes, or enable/disable all classes at
You can disable specific classes, or enable/disable all classes at
once:
<simplelist>
<member>
Expand All @@ -1166,14 +1163,24 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
(<option>-a</option>) except for GC events (<option>g</option>).
</para>

<para>
For spark events there are two modes: sampled and fully accurate.
There are various events in the life cycle of each spark, usually
just creating and running, but there are some more exceptional
possibilities. In the sampled mode the number of occurrences of each
kind of spark event is sampled at frequent intervals. In the fully
accurate mode every spark event is logged individually. The latter
has a higher runtime overhead and is not enabled by default.
</para>

<para>
The format of the log file is described by the header
<filename>EventLogFormat.h</filename> that comes with
GHC, and it can be parsed in Haskell using
the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink>
library. To dump the contents of
a <literal>.eventlog</literal> file as text, use the
tool <literal>ghc-events-show</literal> that comes with
tool <literal>ghc-events show</literal> that comes with
the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink>
package.
</para>
Expand Down

0 comments on commit 050f714

Please sign in to comment.