[commit: ghc] master: users-guide: Add documentation for JSON profile format (b494689)
git at git.haskell.org
git at git.haskell.org
Sun Feb 26 22:26:27 UTC 2017
Repository : ssh://git@git.haskell.org/ghc
On branch : master
Link : http://ghc.haskell.org/trac/ghc/changeset/b494689c30fd0394423f264792530d1f352e1ee7/ghc
>---------------------------------------------------------------
commit b494689c30fd0394423f264792530d1f352e1ee7
Author: Ben Gamari <bgamari.foss at gmail.com>
Date: Sun Feb 26 16:21:09 2017 -0500
users-guide: Add documentation for JSON profile format
Reviewers: austin
Subscribers: thomie
Differential Revision: https://phabricator.haskell.org/D3184
>---------------------------------------------------------------
b494689c30fd0394423f264792530d1f352e1ee7
docs/users_guide/profiling.rst | 153 ++++++++++++++++++++++++++++++++++++++++-
1 file changed, 151 insertions(+), 2 deletions(-)
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index 27b8839..764ee92 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -429,6 +429,155 @@ enclosed between ``+RTS ... -RTS`` as usual):
notorious ``Prelude.head: empty list`` error. See
:ref:`rts-options-debugging`.
+
+JSON profile format
+~~~~~~~~~~~~~~~~~~~
+
+When invoked with the :rts-flag:`-pj` flag the runtime will emit the cost-centre
+profile in a machine-readable JSON format. The top-level object of this format
+has the following properties,
+
+``program`` (string)
+ The name of the program
+``arguments`` (list of strings)
+ The command line arguments passed to the program
+``rts_arguments`` (list of strings)
+ The command line arguments passed to the runtime system
+``initial_capabilities`` (integral number)
+ How many capabilities the program was started with (e.g. using the
+ :rts-flag:`-N` option). Note that the number of capabilities may change
+ during execution due to the ``setNumCapabilities`` function.
+``total_time`` (number)
+ The total wall time of the program's execution in seconds.
+``total_ticks`` (integral number)
+ How many profiler "ticks" elapsed over the course of the program's execution.
+``end_time`` (number)
+ The approximate time when the program finished execution as a UNIX epoch timestamp.
+``tick_interval`` (float)
+ How much time between profiler ticks.
+``total_alloc`` (integer)
+ The cumulative allocations of the program in bytes.
+``cost_centres`` (list of objects)
+ A list of the program's cost centres
+``profile`` (object)
+ The profile tree itself
+
+Each entry in ``cost_centres`` is an object describing a cost-centre of the
+program having the following properies,
+
+``id`` (integral number)
+ A unique identifier used to refer to the cost-centre
+``is_caf`` (boolean)
+ Whether the cost-centre is a Constant Applicative Form (CAF)
+``label`` (string)
+ A descriptive string roughly identifying the cost-centre.
+``src_loc`` (string)
+ A string describing the source span enclosing the cost-centre.
+
+The profile data itself is described by the ``profile`` field, which contains a
+tree-like object (which we'll call a "cost-centre stack" here) with the
+following properties,
+
+``id`` (integral number)
+ The ``id`` of a cost-center listed in the ``cost_centres`` list.
+``entries`` (integral number)
+ How many times was this cost-centre entered?
+``ticks`` (integral number)
+ How many ticks was the program's execution inside of this cost-centre? This
+ does not include child cost-centres.
+``alloc`` (integral number)
+ How many bytes did the program allocate while inside of this cost-centre?
+ This does not include allocations while in child cost-centres.
+``children`` (list)
+ A list containing child cost-centre stacks.
+
+For instance, a simple profile might look like this,
+
+.. code-block:: json
+
+ {
+ "program": "Main",
+ "arguments": [
+ "nofib/shootout/n-body/Main",
+ "50000"
+ ],
+ "rts_arguments": [
+ "-pj",
+ "-hy"
+ ],
+ "end_time": "Thu Feb 23 17:15 2017",
+ "initial_capabilities": 0,
+ "total_time": 1.7,
+ "total_ticks": 1700,
+ "tick_interval": 1000,
+ "total_alloc": 3770785728,
+ "cost_centres": [
+ {
+ "id": 168,
+ "label": "IDLE",
+ "module": "IDLE",
+ "src_loc": "<built-in>",
+ "is_caf": false
+ },
+ {
+ "id": 156,
+ "label": "CAF",
+ "module": "GHC.Integer.Logarithms.Internals",
+ "src_loc": "<entire-module>",
+ "is_caf": true
+ },
+ {
+ "id": 155,
+ "label": "CAF",
+ "module": "GHC.Integer.Logarithms",
+ "src_loc": "<entire-module>",
+ "is_caf": true
+ },
+ {
+ "id": 154,
+ "label": "CAF",
+ "module": "GHC.Event.Array",
+ "src_loc": "<entire-module>",
+ "is_caf": true
+ }
+ ...
+ ],
+ "profile": {
+ "id": 162,
+ "entries": 0,
+ "alloc": 688,
+ "ticks": 0,
+ "children": [
+ {
+ "id": 1,
+ "entries": 0,
+ "alloc": 208,
+ "ticks": 0,
+ "children": [
+ {
+ "id": 22,
+ "entries": 1,
+ "alloc": 80,
+ "ticks": 0,
+ "children": []
+ }
+ ]
+ },
+ {
+ "id": 42,
+ "entries": 1,
+ "alloc": 1632,
+ "ticks": 0,
+ "children": []
+ }
+ ]
+ }
+ }
+
+
+
+
+
.. _prof-heap:
Profiling memory usage
@@ -892,8 +1041,8 @@ The flags are:
.. _manipulating-hp:
-Manipulating the hp file
-~~~~~~~~~~~~~~~~~~~~~~~~
+Manipulating the ``hp`` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(Notes kindly offered by Jan-Willem Maessen.)
More information about the ghc-commits
mailing list