NAME

  reqstat - Report Request Statistics

SYNOPSIS:  

  ./reqstat [delay] [count] [hostname]

DESCRIPTION

  reqstat reports information about your applications requests per second, request latency, and excess
  threshold.  This is commonly used for website HTML pages however can be applied to any process.

  reqstat produces the following basic RPS output in a CSV format

  epoch - Unix timestamp seconds since EPOCH
  time  - Human readable HHMMSS
  rps   - Completed requests per second
  avg_req - The average request time in milliseconds, e.g. the latency of your requests
  last - The last recorded total request time in milliseconds
  %comp - The percentage of requests completed

  reqstat also records excess threshold statistics above a given time

  threshold - A pre-configured and customized millisecond threshold  (defaults to 150)
  exceed - The number of request per second that exceed the threshold
  last_excess - The last recorded total request time in milliseconds that exceeded the threshold
   
  The header line does not repeat. This is only provided as the first line of output.

  epoch,time,rps,avg_req,last,%comp,---,threshold,exceed,last_excess


OPTIONS

  reqstat requires no arguments to work by default. If no arguments are provided the output will run 
  1 minute (60 seconds).

  delay is the delay between updates in seconds.  If no delay is specified this defaults to 5
  count is the number of updates.  If no count is specified this defaults to 12. Set to 0 for infinite.
  servername.  If no value is specified this defaults to localhost.


EXAMPLES

  $ ./reqstat 1 3
  epoch,time,rps,avg_req,last,%comp,---,threshold,exceed,last_excess
  1307723108,162508,22,90.55,83.65,42,---,150,4,157.77
  1307723109,162509,14,149.64,296.26,25,---,150,6,296.26
  1307723110,162510,25,140.20,175.62,52,---,150,11,175.62

  $ ./reqstat 5 5
  epoch,time,rps,avg_req,last,%comp,---,threshold,exceed,last_excess
  1307723122,162522,25,125.92,75.25,48,---,150,9,175.55
  1307723127,162527,24,107.33,6.97,48,---,150,6,188.45
  1307723132,162532,25,118.39,97.63,50,---,150,8,151.37
  1307723137,162537,22,120.51,88.62,42,---,150,5,168.56
  1307723142,162542,26,106.62,6.12,51,---,150,6,167.81

  Several visualizations can be found at http://ronaldbradford.com/blog/visualizing-reqstat-2011-09-28/

CONFIGURATION

  reqstat processes statistics gathered by your application and stored in memcached. The following is 
  an example for PHP code for a normal website.

  Add at the beginning of your HTTP requests add the following code:

  <?php
  $_generate_start = microtime(true);
  $m = new Memcached(); 
  $m->addServer('localhost',11211); 
  $m->setOption(Memcached::OPT_PREFIX_KEY, 'reqstat:');
  $m->increment('requests');
  ?>


  Add at the end of your HTTP requests (ie. just before the </body></html> tag)

  <?php
  $m->increment('completed_requests');
  $time = ceil((microtime(true) - $_generate_start)*1000);
  $m->increment('total_request_time',$time);
  $m->set('last_request_time',$time);
  $threshold = $m->get('request_threshold');
  if (empty($threshold)) $threshold = 150;
  if ($time > $threshold) {
    $m->increment('excess_requests');
    $m->set('last_excess_request_time',$time);
  }
  ?>
  
  If you would also like to embed your page generation time with your HTTP response, 
  add the following just before the </body> tag 

  <?php echo '<div id="_generated">'.  $time .'</div>'; ?>

  In your CSS add the following
  #_generated  { display: none; }

PRE REQUISITES

  reqstat requires a local instance of memcached installed and your application code to record statistics.

  On Ubuntu:
  $ sudo apt-get install -y memcached libmemcached-tools php5-memcached

  Confirmation steps:
  1. Packages installed (e.g. Ubuntu 12.04 LTS)

  $ sudo dpkg -l | grep mem
  ii  libmemcached-tools       0.44-1.1build1         Commandline tools for talking to memcached via libmemcached
  ii  libmemcached6            0.44-1.1build1         A C and C++ client library to the memcached server
  ii  memcached                1.4.13-0ubuntu2        A high-performance memory object caching system
  ii  memtest86+               4.20-1.1ubuntu1        thorough real-mode memory tester
  ii  php5-memcached           1.0.2-2                memcached extension module for PHP5, uses libmemcached

  NOTE: On older distros, you may need to install libmemcached2 instead of libmemcached-tools

  2. PHP Memcached configured
  $ php -i | grep memcached

  /etc/php5/cli/conf.d/memcached.ini,
  memcached
  memcached support => enabled
  libmemcached version => 0.44
  Registered save handlers => files user memcached 

  3. Memcached running
  $ ps -ef | grep memcached
  nobody   24304     1  0 03:39 ?        00:00:00 /usr/bin/memcached -m 64 -p 11211 -u nobody -l 127.0.0.1

  4. Configured on system startup
  $ ls -l /etc/rc3.d/*memcached
  lrwxrwxrwx 1 root root 19 2011-06-03 03:39 /etc/rc3.d/S20memcached -> ../init.d/memcached


FUTURE FEATURES

  TBD

SEE ALSO

  memcached (http://memcached.org/), php (http://php.net)

AUTHORS

  Written by Ronald Bradford <[email protected]>