Metadata-Version: 1.1
Name: bench
Version: 2.0
Summary: Benchmark resources usage
Home-page: http://zhanxw.com/bench
Author: Xiaowei Zhan
Author-email: zhanxw@gmail.com
License: UNKNOWN
Download-URL: https://pypi.python.org/pypi/bench
Description: 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
        --------
        
        - Example 1: simple command
        
        ::
        
            > monitor.py sleep 2
            pid     ppid    cwd     cmd     utime   stime   rtime   maxRss  maxVms  avgRss  avgVms
            99627   99626   /home/zhanxw/mycode/bench       sleep 2 0.0     0.0     1.8569419384    835584  6066176 835584  6066176
        
        - 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    cwd     cmd     utime   stime   rtime   maxRss  maxVms  avgRss  avgVms
            100673  100672  /home/zhanxw/mycode/bench       sh -c sleep 2 & sleep 4 & seq 1000000 >/dev/null & wait 0.0     0.0     3.6947889328    897024  4558848 897024  4558848
            100674  100673  /home/zhanxw/mycode/bench       sleep 2 0.0     0.0     1.68072605133   684032  6066176 684032  6066176
            100675  100673  /home/zhanxw/mycode/bench       sleep 4 0.0     0.0     3.86425089836   700416  6066176 700416  6066176
        
        - Example 3: generate benmarking metrics to external file
        
        ::
            > monitor.py -t -o burnCpu ./burnCpu
            [1440476547.641628, 104060, 104059, '/home/zhanxw/mycode/bench/src', ['./burnCpu'], pcputimes(user=0.0, system=0.0), pmem(rss=1425408, vms=12984320)]
            [1440476547.79734, 104060, 104059, '/home/zhanxw/mycode/bench/src', ['./burnCpu'], pcputimes(user=0.15, system=0.0), pmem(rss=1425408, vms=12984320)]
            [1440476547.960703, 104060, 104059, '/home/zhanxw/mycode/bench/src', ['./burnCpu'], pcputimes(user=0.32, system=0.0), pmem(rss=1425408, vms=12984320)]
            [1440476548.127665, 104060, 104059, '/home/zhanxw/mycode/bench/src', ['./burnCpu'], pcputimes(user=0.48, system=0.0), pmem(rss=1425408, vms=12984320)]
            ...
            
        Additional result are stored in *burnCpu.csv*, *burnCpu.trace.csv* in the Comma-separated format (CSV).
        
        *burnCpu.csv* content
        
        ::
        
            pid,ppid,cwd,cmd,utime,stime,rtime,maxRss,maxVms,avgRss,avgVms
            104060,104059,/home/zhanxw/mycode/bench/src,./burnCpu,5.88,0.0,5.87858390808,1425408,12984320,1425408,12984320
        
        *burnCpu.trace.csv* content
        
        ::
        
            pid,ppid,cwd,cmd,utime,stime,rtime,rss,vms
            104060,104059,/home/zhanxw/mycode/bench/src,./burnCpu,0.0,0.0,0.0,1425408,12984320
            104060,104059,/home/zhanxw/mycode/bench/src,./burnCpu,0.15,0.0,0.155711889267,1425408,12984320
            104060,104059,/home/zhanxw/mycode/bench/src,./burnCpu,0.32,0.0,0.319074869156,1425408,12984320
            104060,104059,/home/zhanxw/mycode/bench/src,./burnCpu,0.48,0.0,0.486037015915,1425408,12984320
            104060,104059,/home/zhanxw/mycode/bench/src,./burnCpu,0.65,0.0,0.653388023376,1425408,12984320
            ...
        
        
        By using the trace output file, *burnCpu.trace.csv*, you can draw benchmarking graphs, such as: 
        
        .. image:: http://zhanxw.com/bench/burnCpu.mon.png
        
        
        NOTE
        ----
        
         Implementation details: python will spawn a child process to collect runtime resources usage details. 
         There are two types of  monitor process: (1) a main monitor process will spawn user specified command, call waitpid() until the spawned process finishes;
         (2) other montiro process will monitor the command process and its child processes. Both monitor process will collect resource usages
         and put them in a process safe queue, in which usage statistics are calculuated or saved.
         Since version 2.0, only the second monitoring methods are used for coding simplicity.
         The monitor process will check CPU and memory metrics at a time interval.
        
         The deprecated option *-s* use shell (/bin/sh) to execute commands. It's a convenient feature but comes with some shell exploit hazards. You can use "sh -c" if needed.
         
         bench requires psutil_ to collect basic benchmarking metrics, and suggests numpy_ and matplotlib_ to generate benchmark graphs on users' own efforts.
        
        .. _psutil: https://code.google.com/p/psutil/
        
        Contact
        -------
        
          Xiaowei Zhan<zhanxw[at]gmail.com>
          
        
Keywords: benchmark,process,monitor
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Other Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Requires: psutil
