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

  1) the help command will list the available and unavailable workloads:

      $ ./nfsometer.py --help
      [snip]

       Available workloads:
         cthon
         dd_100m_100k
         dd_100m_1k
         gitclone
         kernel
         python

       Unavailable workloads:
         filebench_fileserver - Command not found: filebench
         filebench_networkfs  - Command not found: filebench
         filebench_varmail    - Command not found: filebench
         filebench_webserver  - Command not found: filebench
         iozone               - Command not found: iozone
         iozone_direct        - Command not found: iozone

       [snip]

     In this example there are unavailable workloads because iozone and 
     filebench are not installed.  To use these workloads, install iozone 
     and filebench in a standard location.


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

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

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


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

   1) ./nfsometer.py -n 3 -m 'v3|v4.0' server:/export cthon

   2) 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

  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.

   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


Example 3: 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

Server admin interface:
=========================

 Servers may support toggling different nfs related options, such as: turning
 off PNFS, delegations, etc.  This script interface provides an API to call
 out to different types of servers and toggle such settings.
 The script also supports a health check call to make sure that the
 server is in a good state before and after each step.

 This example will run 1 trace of every test for every mount option X
 server setting that is supported by the NTAP script:

  # ./nfsometer.py --admin-script=./scripts/ntap.sh --admin-server=admin@cluster-mgmt..example.com cluster-node1.example.com:/export

Remote path:
=========================

 To test the effect of PNFS in some cluster environments, it is useful to test
 against local volumes (MDS == DS) and remote volumes (MDS != DS).
 The nfsometer.py script assumes that the path passed as the argument in
 <server:path> is a volume local to the node that is specified by the server
 portion.  To add a 'remote' path (and an addition test run for every existing
 test run against this path), use the --remote-path argument.

  # ./nfsometer.py --admin-script=./scripts/ntap.sh --admin-server=admin@cluster-mgmt.example.com --remote-path=/export_remote_to_node1 cluster-node1.example.com:/export

Client script:
=========================

 Like the server-admin script, the client script allows client side toggling
 of parameters. This is especially useful evaluating new code - you can
 instrument some sysctl variables and use this script to try different
 settings.

 To use client-scripts add your custom instrumentation to the script making sure
 that both "client.sh <param_name> get" and "client.sh <param_name> set" work.

 Then, run something like this (where <param_name> is 'foo'):

 # ./nfsometer.py --client-script=./scripts/client.sh --client-arg="foo=1,2,3,4"

 And this will have traces for:
 v3,foo=1 v3,foo=2 v3,foo=3 v3,foo=4
 v4.0,foo=1 v4.0,foo=2 v4.0,foo=3 v4.0,foo=4
 v4.1,foo=1 v4.1,foo=2 v4.1,foo=3 v4.1,foo=4

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.

