.. mode: -*- rst -*-

Monitor
=======

:Tag: design.mps.monitor
:Author: Gareth Rees
:Date: 2018-09-15
:Status: draft design
:Revision: $Id$
:Copyright: See section `Copyright and License`_.
:Index terms: pair: monitor; design


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

_`.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.

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

_`.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:

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

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

_`.req.state.stopped`: that has finished running.

It should be possible to see:

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

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

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

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

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

_`.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]
   "Setting up and running the monitor"; Gareth Rees;
   Ravenbrook Limited; 2018-06-27;
   <https://info.ravenbrook.com/mail/2018/06/27/10-51-04/0/>.

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


Document History
----------------

- 2018-09-14 GDR_ Created based on [GDR_2018-06-27]_.

.. _GDR: https://www.ravenbrook.com/consultants/gdr/


Copyright and License
---------------------

Copyright © 2018–2020 `Ravenbrook Limited <https://www.ravenbrook.com/>`_.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
