Monitor Process Resources Usage
===============================

| Bench aims to be a handy tool with these functions:
|  - Monitor CPU time (user time, sys time, real time)
|  - Monitor memory usage (vms usage, rss usage)
|  - Output to TSV(tab-delimited files)
|  - Output benchmarking metrics
|  - Visualize benchmarking over time

Examples
========

We showed several examples below. **Please note that all output are
tabularized manually.**

-  Example 1: simple command

   | $> monitor.py sleep 2
   | pid ppid utime stime rtime rss vms maxRss maxVms avgRss avgVms cwd
     cmd
   | 133692 133675 0.0 0.0 1.9368159771 774144 6066176 774144 6066176
     774144.0 6066176.0 /home/zhanxw/mycode/bench/scripts sleep 2

-  Example 2: complex shell commands with samping interval equaing 0.5
   second

   | $> monitor.py sh -c 'sleep 2 & sleep 4 & seq 1000000 >/dev/null &
     wait'
   | pid ppid utime stime rtime rss vms maxRss maxVms avgRss avgVms cwd
     cmd
   | 135004 134985 0.0 0.0 3.9532430172 798720 4558848 798720 4558848
     798720.0 4558848.0 /home/zhanxw/mycode/bench/scripts sh -c sleep 2
     & sleep 4 & seq 10000000 >/dev/null & wait
   | 135006 135004 0.0 0.0 3.95348381996 655360 6066176 655360 6066176
     655360.0 6066176.0 /home/zhanxw/mycode/bench/scripts sleep 4
   | 135005 135004 0.0 0.0 1.83160495758 774144 6066176 774144 6066176
     774144.0 6066176.0 /home/zhanxw/mycode/bench/scripts sleep 2
   | 135007 135004 0.05 0.0 0.0599648952484 720896 6090752 720896
     6090752 720896.0 6090752.0 /home/zhanxw/mycode/bench/scripts seq
     10000000

-  Example 3: generate benmarking metrics to external file

The small program, burnCpu, will keep CPU running for several seconds.
Its source code is under src/.

::

    $> monitor.py -t -o burnCpu ./burnCpu
    pid     ppid    utime  stime  rtime            rss      vms       cwd                                cmd
    135471  135454  0.04   0.0    0.0441780090332  1449984  12984320  /home/zhanxw/mycode/bench/scripts  ../src/burnCpu
    135471  135454  0.2    0.0    0.205282926559   1449984  12984320  /home/zhanxw/mycode/bench/scripts  ../src/burnCpu
    135471  135454  0.38   0.0    0.381079912186   1449984  12984320  /home/zhanxw/mycode/bench/scripts  ../src/burnCpu
    ...

Additional result are stored in *burnCpu.csv*, *burnCpu.trace.csv* in
the Comma-separated format (CSV).

*burnCpu.csv* content

::

    pid,ppid,utime,stime,rtime,rss,vms,maxRss,maxVms,avgRss,avgVms,cwd,cmd
    144433,144416,5.4,0.0,5.40555810928,1404928,12984320,1404928,12984320,1404928.0,12984320.0,/home/zhanxw/mycode/bench/scripts,../src/burnCpu

*burnCpu.trace.csv* content

::

    pid,ppid,utime,stime,rtime,rss,vms,cwd,cmd
    144433,144416,0.03,0.0,0.0423669815063,1404928,12984320,/home/zhanxw/mycode/bench/scripts,../src/burnCpu
    144433,144416,0.19,0.0,0.20046210289,1404928,12984320,/home/zhanxw/mycode/bench/scripts,../src/burnCpu
    144433,144416,0.36,0.0,0.373480081558,1404928,12984320,/home/zhanxw/mycode/bench/scripts,../src/burnCpu
    ...

By using the trace output file, *burnCpu.trace.csv*, you can draw
benchmarking graphs, such as:

|image|

Notes
=====

| Shell (/bin/sh) can be used to execute commands. You can use "sh -c
  'command arg1 arg2 ... '" (see Example 2).
| Bench requires `psutil <https://pypi.python.org/pypi/psutil>`__ to
  collect basic benchmarking metrics, and
| requires numpy and pandas for statistical calculations. We used psutil
  version 3.1.1 in development.

Contact
=======

Xiaowei Zhan<zhanxw[at]gmail.com

.. |image| image:: http://zhanxw.com/bench/burnCpu.png
