eventlog-formats.rst 4.18 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
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``
32

33 34 35
   * ``Word8``: Profile ID
   * ``Word64``: Sampling period in nanoseconds
   * ``Word32``: Sample break-down type. One of,
36

37 38 39 40 41 42 43
      * ``HEAP_PROF_BREAKDOWN_COST_CENTER`` (output from :rts-flag:`-hc`)
      * ``HEAP_PROF_BREAKDOWN_CLOSURE_DESCR`` (output from :rts-flag:`-hd`)
      * ``HEAP_PROF_BREAKDOWN_RETAINER`` (output from :rts-flag:`-hr`)
      * ``HEAP_PROF_BREAKDOWN_MODULE`` (output from :rts-flag:`-hm`)
      * ``HEAP_PROF_BREAKDOWN_TYPE_DESCR`` (output from :rts-flag:`-hy`)
      * ``HEAP_PROF_BREAKDOWN_BIOGRAPHY`` (output from :rts-flag:`-hb`)
      * ``HEAP_PROF_BREAKDOWN_CLOSURE_TYPE`` (output from :rts-flag:`-hT`)
44

45
   * ``String``: Module filter
46
   * ``String``: Closure description filter
47
   * ``String``: Type description filter
48 49 50 51
   * ``String``: Cost centre filter
   * ``String``: Cost centre stack filter
   * ``String``: Retainer filter
   * ``String``: Biography filter
52

niteria's avatar
niteria committed
53
Cost centre definitions
54 55
^^^^^^^^^^^^^^^^^^^^^^^

niteria's avatar
niteria committed
56
A variable-length packet produced once for each cost centre,
57 58

 * ``EVENT_HEAP_PROF_COST_CENTRE``
59

niteria's avatar
niteria committed
60
   * ``Word32``: cost centre number
61 62 63 64
   * ``String``: label
   * ``String``: module
   * ``String``: source location
   * ``Word8``: flags
65

niteria's avatar
niteria committed
66
     * bit 0: is the cost-centre a CAF?
67 68 69 70 71


Sample event types
~~~~~~~~~~~~~~~~~~

niteria's avatar
niteria committed
72
A sample (consisting of a list of break-down classes, e.g. cost centres, and
73 74
heap residency sizes), is to be encoded in the body of one or more events.

75
We normally mark the beginning of a new sample with an ``EVENT_HEAP_PROF_SAMPLE_BEGIN``
76 77 78
event,

 * ``EVENT_HEAP_PROF_SAMPLE_BEGIN``
79

80 81
   * ``Word64``: sample number

82 83 84 85 86 87 88 89 90 91 92 93
Biographical profiling samples start with the ``EVENT_HEAP_BIO_PROF_SAMPLE_BEGIN``
event. These events also include a timestamp which indicates when the sample
was taken. This is because all these samples will appear at the end of
the eventlog due to how the biographical profiling mode works. You can
use the timestamp to reorder the samples relative to the other events.

 * ``EVENT_HEAP_BIO_PROF_SAMPLE_BEGIN``

   * ``Word64``: sample number
   * ``Word64``: eventlog timestamp in ns


94 95 96 97 98
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.

99 100 101 102 103 104 105 106
At the end of the sample period the ``EVENT_HEAP_PROF_SAMPLE_END`` event if
emitted. This is useful to properly delimit the sampling period and to record
the total time spent profiling.


 * ``EVENT_HEAP_PROF_SAMPLE_END``
   * ``Word64``: sample number

107

niteria's avatar
niteria committed
108
Cost-centre break-down
109 110 111
^^^^^^^^^^^^^^^^^^^^^^

A variable-length packet encoding a heap profile sample broken down by,
niteria's avatar
niteria committed
112
 * cost-centre (``-hc``)
113

114

115
 * ``EVENT_HEAP_PROF_SAMPLE_COST_CENTRE``
116

117 118 119
   * ``Word8``: Profile ID
   * ``Word64``: heap residency in bytes
   * ``Word8``: stack depth
niteria's avatar
niteria committed
120
   * ``Word32[]``: cost centre stack starting with inner-most (cost centre numbers)
121 122 123 124 125 126


String break-down
^^^^^^^^^^^^^^^^^

A variable-length event encoding a heap sample broken down by,
127

128 129 130 131
 * type description (``-hy``)
 * closure description (``-hd``)
 * module (``-hm``)

132
 * ``EVENT_HEAP_PROF_SAMPLE_STRING``
133

134
   * ``Word8``: Profile ID
135 136
   * ``Word64``: heap residency in bytes
   * ``String``: type or closure description, or module name