Monitor

author Gareth Rees
date 2018-09-15
index terms pair: monitor; design
revision //info.ravenbrook.com/project/mps/master/design/monitor.txt#7
status draft design
tag design.mps.monitor

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

.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).

Installation and usage

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

  1. 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

  2. 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

  3. 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

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

  5. 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

  6. 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):

    Screenshot of the MPS monitor showing a run of the amcss smoke test.

  7. 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](1, 2) "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