diff options
Diffstat (limited to 'docs/users_guide')
| -rw-r--r-- | docs/users_guide/8.2.1-notes.rst | 4 | ||||
| -rw-r--r-- | docs/users_guide/eventlog-formats.rst | 119 | ||||
| -rw-r--r-- | docs/users_guide/index.rst | 1 | ||||
| -rw-r--r-- | docs/users_guide/profiling.rst | 24 |
4 files changed, 144 insertions, 4 deletions
diff --git a/docs/users_guide/8.2.1-notes.rst b/docs/users_guide/8.2.1-notes.rst index 7b271cd054..2ae804dc56 100644 --- a/docs/users_guide/8.2.1-notes.rst +++ b/docs/users_guide/8.2.1-notes.rst @@ -56,6 +56,10 @@ Runtime system - TODO FIXME. +- The :ref:`heap profiler <prof-heap>` can now emit heap census data to the GHC + event log, allowing heap profiles to be correlated with other tracing events + (see :ghc-ticket:`11094`). + Build system ~~~~~~~~~~~~ diff --git a/docs/users_guide/eventlog-formats.rst b/docs/users_guide/eventlog-formats.rst new file mode 100644 index 0000000000..74a62f2bd3 --- /dev/null +++ b/docs/users_guide/eventlog-formats.rst @@ -0,0 +1,119 @@ +Eventlog encodings +================== + +This section documents the encodings of the events emitted to GHC's +:ref:`event log <rts-eventlog>`. These events can include information about the +thread scheduling events, garbage collection statistics, profiling information, +user-defined tracing events. + +This section is intended for implementors of tooling which consume these events. + + +.. _heap-profiler-events: + +Heap profiler event log output +------------------------------ + +The heap profiler can produce output to GHC's event log, allowing samples to +be correlated with other event log events over the program's lifecycle. + +This section defines the layout of these events. The ``String`` type below is +defined to be a UTF-8 encoded NUL-terminated string. + +Metadata event types +~~~~~~~~~~~~~~~~~~~~ + +Beginning of sample stream +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A single fixed-width event emitted during program start-up describing the samples that follow. + + * ``EVENT_HEAP_PROF_BEGIN`` + * ``Word8``: Profile ID + * ``Word64``: Sampling period in nanoseconds + * ``Word32``: Sample break-down type. One of, + * ``SAMPLE_TYPE_COST_CENTER`` (output from ``-hc``) + * ``SAMPLE_TYPE_CLOSURE_DESCR`` (output from ``-hd``) + * ``SAMPLE_TYPE_RETAINER`` (output from ``-hr``) + * ``SAMPLE_TYPE_MODULE`` (output from ``-hm``) + * ``SAMPLE_TYPE_TYPE_DESCR`` (output from ``-hy``) + * ``SAMPLE_TYPE_BIOGRAPHY`` (output from ``-hb``) + * ``String``: Cost centre filter + * ``String``: Closure description filter + * ``String``: Retainer filter + * ``String``: Module filter + * ``String``: Type description filter + +Cost center definitions +^^^^^^^^^^^^^^^^^^^^^^^ + +A variable-length packet produced once for each cost center, + + * ``EVENT_HEAP_PROF_COST_CENTRE`` + * ``Word32``: cost center number + * ``String``: label + * ``String``: module + * ``String``: source location + * ``Word8``: flags + * bit 0: is the cost-center a CAF? + + +Sample event types +~~~~~~~~~~~~~~~~~~ + +A sample (consisting of a list of break-down classes, e.g. cost centers, and +heap residency sizes), is to be encoded in the body of one or more events. + +We mark the beginning of a new sample with an ``EVENT_HEAP_PROF_SAMPLE_BEGIN`` +event, + + * ``EVENT_HEAP_PROF_SAMPLE_BEGIN`` + * ``Word64``: sample number + +A heap residency census will follow. Since events may only be up to 2^16^ bytes +in length a single sample may need to be split among multiple +``EVENT_HEAP_PROF_SAMPLE`` events. The precise format of the census entries is +determined by the break-down type. + + +Cost-center break-down +^^^^^^^^^^^^^^^^^^^^^^ + +A variable-length packet encoding a heap profile sample broken down by, + * cost-center (``-hc``) + * retainer (``-hr``) + + * ``EVENT_HEAP_PROF_SAMPLE`` + * ``Word8``: Profile ID + * ``Word64``: heap residency in bytes + * ``Word8``: stack depth + * ``Word32[]``: cost center stack starting with inner-most (cost center numbers) + + +String break-down +^^^^^^^^^^^^^^^^^ + +A variable-length event encoding a heap sample broken down by, + * type description (``-hy``) + * closure description (``-hd``) + * module (``-hm``) + + * ``EVENT_HEAP_PROF_SAMPLE`` + * ``Word8``: Profile ID + * The event shall contain packed pairs of, + * ``String``: type description + * ``Word64``: heap residency in bytes + + +Biography break-down +^^^^^^^^^^^^^^^^^^^^ + +A fixed-length event encoding a biography heap sample. + + * ``EVENT_HEAP_PROF_SAMPLE`` + * ``Word8``: Profile ID + * ``Word64``: Void + * ``Word64``: Lag + * ``Word64``: Use + * ``Word64``: Inherent use + * ``Word64``: Drag diff --git a/docs/users_guide/index.rst b/docs/users_guide/index.rst index b7ff4c091e..57b04c64a4 100644 --- a/docs/users_guide/index.rst +++ b/docs/users_guide/index.rst @@ -26,6 +26,7 @@ Contents: utils win32-dlls bugs + eventlog-formats editing-guide diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst index 4d0bb3a3ed..daae7805d5 100644 --- a/docs/users_guide/profiling.rst +++ b/docs/users_guide/profiling.rst @@ -425,10 +425,14 @@ To generate a heap profile from your program: 2. Run it with one of the heap profiling options described below (eg. :rts-flag:`-h` for a basic producer profile). This generates the file - ``prog.hp``. + :file:`{prog}.hp`. -3. Run ``hp2ps`` to produce a Postscript file, ``prog.ps``. The - ``hp2ps`` utility is described in detail in :ref:`hp2ps`. + If the :ref:`event log <rts-eventlog>` is enabled (with the :rts-flag:`-l` + runtime system flag) heap samples will additionally be emitted to the GHC + event log (see :ref:`heap-profiler-events` for details about event format). + +3. Run :command:`hp2ps` to produce a Postscript file, :file:`{prog}.ps`. The + :command:`hp2ps` utility is described in detail in :ref:`hp2ps`. 4. Display the heap profile using a postscript viewer such as Ghostview, or print it out on a Postscript-capable printer. @@ -485,6 +489,18 @@ following RTS options select which break-down to use: Break down the graph by biography. Biographical profiling is described in more detail below (:ref:`biography-prof`). +.. rts-flag:: -l + + :noindex: + + .. index:: + single: eventlog; and heap profiling + + Emit profile samples to the :ref:`GHC event log <rts-eventlog>`. + This format is both more expressive than the old ``.hp`` format + and can be correlated with other events over the program's runtime. + See :ref:`heap-profiler-events` for details on the produced event structure. + 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 @@ -747,7 +763,7 @@ Usage: hp2ps [flags] [<file>[.hp]] -The program :command:`hp2ps` program converts a heap profile as produced +The program :command:`hp2ps` program converts a ``.hp`` file produced by the ``-h<break-down>`` runtime option into a PostScript graph of the heap profile. By convention, the file to be processed by :command:`hp2ps` has a ``.hp`` extension. The PostScript output is written to :file:`{file}@.ps`. |