.. mode: -*- rst -*-
Monitor
=======
:Tag: design.mps.monitor
:Author: Gareth Rees
:Date: 2018-09-15
:Status: draft design
:Revision: $Id: //info.ravenbrook.com/project/mps/master/design/monitor.txt#7 $
: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;
.
.. [GR_2004-12-02]
"RE: MPS, working set, and address space"; Göran Rydqvist;
Configura Sverige AB; 2004-12-02;
.
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 `_.
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.