source: main/waeup.sirp/branches/ulif-stress-multimech/README.txt @ 7484

waeup.stresstest
****************

This package provides stresstests for *existing* WAeUP SIRP sites.

It deploys the Python multi-mechanize programme/library to fire tons
of requests against a running site. So, you don't want to use it with
sites that are under load already. The requests try to simulate users
using the portal simultanously.

multi-mechanize registers the numbers and latencies of single requests
and generates graphics/tables with the results. This way you can see
what actions/requests need how much time. You can also see how the
server reacts when many concurrent users use the portal.

`waeup.stresstest` is code-wise independent from `waeup.sirp`. You can
run it on any machine that can do HTTP requests to the target machine
(which means the machine that should be stress-tested).

Installation is a bit difficult (numpy and matplotlib, two complex
Python libs for statistical computations) are required and not easily
installable in the usual buildout-way (well, numpy is but matplotlib
is a constant source of trouble in that respect). Please refer to the
``Installation`` section below.

Installation
============

The following steps are tested on Ubuntu Linux only.

Requirements
------------

* Python 2.6 or Python 2.7.

* Python packages numpy, mechanize and matplotlib

With recent Ubuntu installs it should be possible to install the
required libs systemwide by doing::

  $ sudo apt-get install python-numpy
  $ sudo apt-get install python-matplotlib
  $ sudo apt-get install python-mechanize

With older Ubuntu releases (for instance ones, that do not ship with
Python 2.6 or newer), you have to install Python 2.6 or 2.7 locally
and then install both packages using ``easy_install`` or ``pip``.

The latter is also possible in ``virtualenv`` environments, i.e. if
you don't want to install the additional packages system-wide.

Install of ``multi-mechanize`` then is especially, ehrm, improvable,
because this package (yet) lacks support for any package management
(no setup.py or similar; just plain code packed in a ZIP file for
download).

We therefore packed the sources of version "1.011" (?) here and added
some own project which can be run. See usage instructions below.

Usage
=====

Quick guide:

1) Make sure configuration is up-to-date in
   `multi-mechanize/projects/sirp1/config.cfg`. This 'project' will
   run against a SIRP portal installed locally as ``app-stress``

2) Create a local waeup.sirp portal running on localhost:8080 and
   named ``app-stress``

3) Start the portal.

4) On the shell, run::

     $ cd multi-mechanize
     $ python multi-mechanize sirp1

The latter tells multi mechanize to run the stress tests in the
``projects/sirp1`` directory. Make sure that the Python interpreter
you use here is the one that has support for matplotlib and numpy.

Results will be as HTML page in ``projects/sirp1/results/``.


Tweaking and Playing Around
===========================

The current stress tests only include simulation of a bunch of users
simultaneously trying to access the portal home page and the portal
applicants page (as anonymous users).

You can tweak and change ``projects/sirp1/test_scripts/`` to do
different things. See http://code.google.com/p/multi-mechanize/ for
first steps/hints.


ToDo
====

multi-mechanize currently makes no use of Python packaging,
entry-points and the like. Improving it in this way and making it a
first-class-citizen of the Python 'packaging' community would be a
first step to make it more useful for others.

Notes
=====

Installing matplotlib with buildout
-----------------------------------

To install `waeup.stresstest` you need matplotlib which in turn
depends on `numpy`. While `numpy` can be installed during
buildout-runs, `matplotlib` is a bit difficult. It does a manual check
for already installed packages and does not detect already fetched
numpy installs. As a result matplotlib cannot be installed easily with
buildout, although there are a few workarounds:

http://comments.gmane.org/gmane.comp.python.distutils.devel/13590

Installing on an old Ubuntu with virtualenv
-------------------------------------------

Just for the logs, this is what I did to make it work::

  $ virtualenv --no-site-packages -p <PATH-TO-PYTHON-2.6> sandbox26
  $ source sandbox26/bin/activate
  $ pip install mechanize
  $ pip install numpy
  $ pip install matplotlib

Then (on a different shell):

  - Started waeup.sirp::

    $ ./bin/sirpctl fg


  - Added a University instance named 'app-stress'

Back on the first shell::

  $ python multi-mechanize.py sirp1