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
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
.. highlight:: none


.. index::
   pair: monitor; design

.. _design-monitor:


Monitor
=======

.. mps:prefix:: design.mps.monitor


Introduction
------------

:mps:tag:`intro` This is the design of the MPS monitor, a graphical user
interface for inspecting the behaviour of the MPS in a client program
by collating the program's telemetry output.

:mps:tag:`readership` This document is intended for any MPS user.

:mps:tag:`source` This is based on [GDR_2018-06-27]_.


Requirements
------------

It should be possible to analyze the behaviour of the
MPS in a client program:

:mps:tag:`req.state.running` that is currently running (job003960_); or

.. _job003960: https://www.ravenbrook.com/project/mps/issue/job003960/

:mps:tag:`req.state.stopped` that has finished running.

It should be possible to see:

:mps:tag:`req.memory.total` the total memory in use by the client program
[GR_2004-12-02]_;

:mps:tag:`req.memory.pool` the memory in use by each pool (job003960_);

:mps:tag:`req.trace` when traces take place (job003960_);

:mps:tag:`req.trace.generation` which generations get collected by each
trace (job003960_);

:mps:tag:`req.time-fraction` the fraction of runtime spent in collections;

:mps:tag:`req.barriers` the rate of barrier hits, to indicate how the barriers
are working (job003921_).

.. _job003921: https://www.ravenbrook.com/project/mps/issue/job003921/



Installation and usage
----------------------

These are placeholder instructions, to be revised when we figure out
the best way to automate them.

#. Build the ``mpseventpy`` program::

        cd code
        nmake /f w3i6mv.nmk VARIETY=cool mpseventpy.exe # Windows
        make -f xci6ll.gmk VARIETY=cool mpseventpy # macOS
        make -f lii6ll.gmk VARIETY=cool mpseventpy # Linux

#. Run ``mpseventpy`` program and redirect the output to ``tool/mpsevent.py``::

        w3i6mv/cool/mpseventpy.exe > ../tool/mpsevent.py # Windows
        xci6ll/cool/mpseventpy > ../tool/mpsevent.py # macOS
        lii6ll/cool/mpseventpy > ../tool/mpsevent.py # Linux

#. Install Python 3.6 (or later). On Windows, there are installers_
   named like ``python-3.6.6-amd64.exe``. On other platforms, you
   probably want to use your package manager, for example::

        sudo port install python36 # macPorts
        sudo apt install python3.6 # Linux

   .. _installers: https://www.python.org/ftp/python/3.6.5/python-3.6.5-amd64.exe

#. On Windows, you’ll want to edit the system environment variables to
   put Python 3.6 on the path.

#. Install Matplotlib and PyQt5. On Windows, the easiest way to do
   this is to launch a command prompt (possibly as administrator, if
   you installed Python somewhere like ``C:/Program Files``) and
   then::

        python -m ensurepip
        python -m pip install matplotlib pyqt5

   On other platforms, you’ll want to use the package manager, for example::

        sudo port install py36-matplotlib py36-pyqt5 # macPorts
        sudo apt install python3-matplotlib python3-pyqt5 # Linux

#. Now, from the ``tool`` subdirectory, you should be able to run the
   monitor::

        cd tool
        ./monitor [FILENAME]

   where FILENAME defaults to mpsio.log. So for example, you could
   compile the ``amcss`` smoke test::

        cd code
        nmake /f w3i6mv.nmk VARIETY=cool amcss.exe # Windows
        make -f xci6ll.gmk VARIETY=cool amcss # macOS
        make -f lli6ll.gmk VARIETY=cool amcss # Linux

   and then run ``amcss`` generating telemetry output::

        cd tool
        MPS_TELEMETRY_FILENAME=mpsio.log MPS_TELEMETRY_CONTROL="arena pool user” ../code/w3i6mv/cool/amcss.exe > /dev/null # Windows
        MPS_TELEMETRY_FILENAME=mpsio.log MPS_TELEMETRY_CONTROL="arena pool user" ../code/xci6ll/cool/amcss > /dev/null # macOS
        MPS_TELEMETRY_FILENAME=mpsio.log MPS_TELEMETRY_CONTROL="arena pool user" ../code/lli6ll/cool/amcss > /dev/null # Linux

   and then launch the monitor on the file you just created::

        cd tool
        ./monitor

   which should show you something like this (the exact graphs will
   depend on the random choices made by ``amcss``):

   .. figure:: monitor.png
       :align: center
       :alt: Screenshot of the MPS monitor showing a run of the amcss smoke test.

#. The monitor is capable of monitoring an application in real-time.
   The pause button on the toolbar pauses the updating of the display
   (but not the application). The zoom and pan tools automatically
   pause the updating too, so after zooming you’ll need to unpause in
   order to resume updating the display.


References
----------

.. [GDR_2018-06-27] Gareth Rees. Ravenbrook Limited. 2018-06-27. "`Setting up and running the monitor <https://info.ravenbrook.com/mail/2018/06/27/10-51-04/0/>`__".

.. [GR_2004-12-02] Göran Rydqvist. Configura Sverige AB. 2004-12-02. "`RE: MPS, working set, and address space <https://info.ravenbrook.com/mail/2004/12/02/07-53-32/0/>`__".