nfsometer -

  A framework for running and reporting performance characteristics of 
  workloads across NFS protocol versions, options and Linux kernels.

About
==================

  author:  Weston Andros Adamson <dros@netapp.com>
  website: http://wiki.linux-nfs.org/wiki/index.php/NFSometer

Dependencies
==================

  nfsometer depends on several third-party packages and will not run without
  them installed.

   - matplotlib - used for graph plotting
   - numpy      - used by matplotlib, stats functions
   - mako       - used for html templating of reports

  On a fedora system the following command will install these packages:

  # sudo yum install python-matplotlib numpy python-mako

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

  nfsometer is designed to be able to run without installation, ie:

  # ./nfsometer.py --help

  nfsometer can also be installed to standard python site-packages and
  executable directories (must be run as root):

  # python setup.py install
  # nfsometer --help

Basic Usage
=================

Example 1: see what workloads are available

  $ ./nfsometer.py -w

  This command will tell you which workloads are available and will tell you
  why workloads are unavailable (if any exist).


Example 2: compare cthon, averaged over 3 runs, across nfs protocol versions

   ./nfsometer.py -n 3 server:/export cthon

  This example uses the default for -o: "-o v3 -o v4 -o v4.1".
  To see the results, open results/index.html in a web browser.


Example 3: compare cthon, averaged over 3 runs, between v3 and v4.0 only

  ./nfsometer.py -n 3 -o v3 -o v4 server:/export cthon

  This example specifies v3 and v4 only.
  To see the results, open results/index.html in a web browser.


Example 4: compare two kernels running iozone workload, averaged over 2 runs,
           across all nfs protocol versions

   1) boot into kernel #1

   2) ./nfsometer.py -n 2 server:/export iozone

   3) boot into kernel #2

   4) ./nfsometer.py -n 2 server:/export iozone

   5) open results/index.html in a web browser

  nfsometer can compare two (or more) kernel versions, but nfsometer has no
  way of building, installing or booting new kernels, so for now this must
  be done manually.  In order for these kernels to be differentiated,
  'uname -a' must be different.
  To see the results, open results/index.html in a web browser.


Example 5: using tags

  Tags (the -t option) can be used to mark nfsometer runs as occurring with
  some configuration not captured by mount options or detectable tags, such
  as different sysctl settings (client side), different server side options,
  or different network conditions.

  1) set server value foo to 2.3

  2) ./nfsometer.py -o v4 -o v4.1 -t foo=2.3

  3) set server value foo to 10

  4) ./nfsometer.py -o v4 -o v4.1 -t foo=10

  What is passed to -t is entirely up to the user - it will not be interpreted
  or checked by nfsometer at all, so be careful!
  To see the results, open results/index.html in a web browser.


Example 6: always options

  The -o flag specifies distinct option sets to run, but sometimes there are
  options that should be present in each.  Instead of writing each one out, you
  can use the -a option:

  ./nfsometer.py -o v3 -o v4 -a sec=krb5 server:/export iozone

  this is equivalent to:

  ./nfsometer.py -o v3,sec=krb5 -o v4,sec=krb5 server:/export iozone


Example 7: using the "custom" workload

  A main use case of nfsometer is the "custom" workload - it allows the user
  to specify the command that nfsometer is to run.

  NOTE: the command's cwd (current working directory) is the runroot created
  on the server.

  NFSOMETER_CMD="echo foo > bar" ./nfsometer server:/export custom

  This will run 3 traces (v3, v4, v4.1) against server:/export of the command:
  echo foo > bar.
  The reports will call this "Custom: echo foo > bar", but you can override the
  name by setting NFSOMETER_NAME.


Example 8: long running nfsometer trace

  The nfsometer.py script currently runs in the foreground.  As such, it
  will be killed if the tty gets a hangup or the connection to the client
  is closed.

  For the time being, ./nfsometer.py should be run in a screen session, or
  run with nohup and the output redirected to a file.

   1) screen -RD
   2) ./nfsometer.py -n 2 server:/export iozone
   3) close terminal window (or ^A^D)
   ...
   4) reattach later with "screen -RD"
   5) once nfsometer.py is done, results will be in results/index.html

Adding a workload
======================

Adding a workload is designed to be very simple.

Copy the 'nfsometer-workload-template' file to a file in the workloads directory
that ends with ".nfsometer", edit this file following the instructions
contained within.

