+ <sect2 id="rts-eventlog">
+ <title>Tracing</title>
+
+ <indexterm><primary>tracing</primary></indexterm>
+ <indexterm><primary>events</primary></indexterm>
+ <indexterm><primary>eventlog files</primary></indexterm>
+
+ <para>
+ When the program is linked with the <option>-eventlog</option>
+ option (<xref linkend="options-linker" />), runtime events can
+ be logged in two ways:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ In binary format to a file for later analysis by a
+ variety of tools. One such tool
+ is <ulink url="http://hackage.haskell.org/package/ThreadScope">ThreadScope</ulink><indexterm><primary>ThreadScope</primary></indexterm>,
+ which interprets the event log to produce a visual parallel
+ execution profile of the program.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ As text to standard output, for debugging purposes.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>-l<optional><replaceable>flags</replaceable></optional></option>
+ <indexterm><primary><option>-l</option></primary><secondary>RTS option</secondary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ Log events in binary format to the
+ file <filename><replaceable>program</replaceable>.eventlog</filename>,
+ where <replaceable>flags</replaceable> is a sequence of
+ zero or more characters indicating which kinds of events
+ to log. Currently there is only one type
+ supported: <literal>-ls</literal>, for scheduler events.
+ </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>show-ghc-events</literal> that comes with
+ the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink>
+ package.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-v</option><optional><replaceable>flags</replaceable></optional>
+ <indexterm><primary><option>-v</option></primary><secondary>RTS option</secondary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ Log events as text to standard output, instead of to
+ the <literal>.eventlog</literal> file.
+ The <replaceable>flags</replaceable> are the same as
+ for <option>-l</option>, with the additional
+ option <literal>t</literal> which indicates that the
+ each event printed should be preceded by a timestamp value
+ (in the binary <literal>.eventlog</literal> file, all
+ events are automatically associated with a timestamp).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ The debugging
+ options <option>-D<replaceable>x</replaceable></option> also
+ generate events which are logged using the tracing framework.
+ By default those events are dumped as text to stdout
+ (<option>-D<replaceable>x</replaceable></option>
+ implies <option>-v</option>), but they may instead be stored in
+ the binary eventlog file by using the <option>-l</option>
+ option.
+ </para>
+ </sect2>
+