[ipbench-cvs] ipbench2/doc/manual manual.sgml,1.1.1.1,1.2

[Peter C. <pc...@us...>]

Update of /cvsroot/ipbench/ipbench2/doc/manual
In directory sfp-cvsdas-1.v30.ch3.sourceforge.com:/tmp/cvs-serv4277

Modified Files:
	manual.sgml 
Log Message:
Add nfs_latency test, fix spelling.


Index: manual.sgml
===================================================================
RCS file: /cvsroot/ipbench/ipbench2/doc/manual/manual.sgml,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** manual.sgml	28 Jun 2004 05:19:13 -0000	1.1.1.1
--- manual.sgml	9 Feb 2010 03:31:40 -0000	1.2
***************
*** 16,20 ****
     
      <copyright>
!       <year>2004</year>
        <holder role='mailto:ia...@ge...'>Ian Wienand</holder>
      </copyright>
--- 16,20 ----
     
      <copyright>
!       <year>2004, 2010</year>
        <holder role='mailto:ia...@ge...'>Ian Wienand</holder>
      </copyright>
***************
*** 39,48 ****
      <sect1>
  	<title>Test setup</title> <para>To run an &ipbench; test you
! 	will require several components to be working together.
  	Firstly, the <emphasis>controller</emphasis> machine is that
  	machine that you are assumed to be sitting at, wanting a set
  	of benchmarking results.  You will farm your work out to
! 	a/some/many <emphasis>client</emphasis> machines that will run
! 	the benchmark at a specific <emphasis>target</emphasis>.
  	Possibly, you at the controller require some information from
  	the target, for example, how much CPU time it used, so may
--- 39,48 ----
      <sect1>
  	<title>Test setup</title> <para>To run an &ipbench; test you
! 	need several components working together.
  	Firstly, the <emphasis>controller</emphasis> machine is that
  	machine that you are assumed to be sitting at, wanting a set
  	of benchmarking results.  You will farm your work out to
! 	a/some/many <emphasis>client</emphasis> machines that will
! 	generate load for a specific <emphasis>target</emphasis>.
  	Possibly, you at the controller require some information from
  	the target, for example, how much CPU time it used, so may
***************
*** 51,56 ****
  	<para>In the above situation, each of the client machines will
  	be running an instance of <literal>ipbenchd</literal>.  Your
! 	target machine may be running an instance of
! 	<literal>ipbenchtd</literal> and you will control the test via
  	the <literal>ipbench</literal> program on your local
  	machine. </para>
--- 51,58 ----
  	<para>In the above situation, each of the client machines will
  	be running an instance of <literal>ipbenchd</literal>.  Your
! 	target machine may also be running an instance of
! 	<literal>ipbenchd</literal> (in <emphasis>target</emphasis>
! 	mode) 
! 	and you will control the test via
  	the <literal>ipbench</literal> program on your local
  	machine. </para>
***************
*** 63,67 ****
  
  	<para>The options should be fairly self explanatory.  Each
! 	test has a number of arguments it can be passed via it's
  	<command>--test-args</command> flag; see the test specific
  	information below for listings and explanations.  If you
--- 65,69 ----
  
  	<para>The options should be fairly self explanatory.  Each
! 	test has a number of arguments it can be passed via its
  	<command>--test-args</command> flag; see the test specific
  	information below for listings and explanations.  If you
***************
*** 70,73 ****
--- 72,83 ----
  	(arguments can be passed with
  	<command>--target-args</command>).</para>
+ 
+ 	<para>One possible gotcha is that the
+ 	<command>--target</command> argument should take the name or IP address
+ 	of the target on the test network, which ideally should be
+ 	isolated from other networks.  Some of the benchmark tests can
+ 	generate enough ethernet traffic to saturate multi-gigabit
+ 	links, so it is important that this not be allowed onto your
+ 	main network.</para>
        </sect1>
  
***************
*** 95,101 ****
  
  	    <para> There are a number of options that can be passed to
! 	  the test.  The options should be passed with the <userinput>--test-args</userinput>
! 	  command line paramater in a simple
! 	  <userinput>"command=value,command1=value1"</userinput> format (note no whitespace).
  	  The test options are </para>
  
--- 105,113 ----
  
  	    <para> There are a number of options that can be passed to
! 	  the test.  The options should be passed with the
! 	  <userinput>--test-args</userinput> 
! 	  command line parameter in a simple
! 	  <userinput>"command=value,command1=value1"</userinput>
! 	  format (note no white-space). 
  	  The test options are </para>
  
***************
*** 181,185 ****
  		    <entry><para>If you specify the
  		    <literal>socktype</literal> as
! 		    <literal>raw</literal> then you must passs the
  		    <literal>ipbench</literal> the
  		    <literal>--target</literal> command as a
--- 193,197 ----
  		    <entry><para>If you specify the
  		    <literal>socktype</literal> as
! 		    <literal>raw</literal> then you must pass the
  		    <literal>ipbench</literal> the
  		    <literal>--target</literal> command as a
***************
*** 230,234 ****
  		    <entry><para>(The number of packets received * the packet size) / (test time)</para></entry>
  		    <entry><para><literal>bits per second</literal></para></entry>
! 		    <entry><para>Each client works out it's achieved throughput, the total shown is the sum of each clients individal throughput</para></entry>
  		  </row>
  		  <row>
--- 242,246 ----
  		    <entry><para>(The number of packets received * the packet size) / (test time)</para></entry>
  		    <entry><para><literal>bits per second</literal></para></entry>
! 		    <entry><para>Each client works out its achieved throughput, the total shown is the sum of each clients individual throughput</para></entry>
  		  </row>
  		  <row>
***************
*** 241,251 ****
  		    <entry><para>(The number of packets sent * the packet size) / (test time)</para></entry>
  		    <entry><para><literal>bits per second</literal></para></entry>
! 		    <entry><para>This should not differ from achieved throughput  unless many packets are sent but not received (ie. dropped)</para></entry>
  		  </row>
  		  <row>
  		    <entry><para><computeroutput>Min</computeroutput></para></entry>
! 		    <entry><para>Miniumum latency</para></entry>
  		    <entry><para><literal>microseconds</literal></para></entry>
! 		    <entry morerows='4'><para>Each client returns all of it's data to the controller where these figures are calculated.</para></entry>
  		  </row>
  		  <row>
--- 253,263 ----
  		    <entry><para>(The number of packets sent * the packet size) / (test time)</para></entry>
  		    <entry><para><literal>bits per second</literal></para></entry>
! 		    <entry><para>This should not differ from achieved throughput  unless many packets are sent but not received (i.e.,. dropped)</para></entry>
  		  </row>
  		  <row>
  		    <entry><para><computeroutput>Min</computeroutput></para></entry>
! 		    <entry><para>Minimum latency</para></entry>
  		    <entry><para><literal>microseconds</literal></para></entry>
! 		    <entry morerows='4'><para>Each client returns all of its data to the controller where these figures are calculated.</para></entry>
  		  </row>
  		  <row>
***************
*** 256,265 ****
  		  <row>
  		    <entry><para><computeroutput>Max</computeroutput></para></entry>
! 		    <entry><para>Maxiumum latency</para></entry>
  		    <entry><para><literal>microseconds</literal></para></entry>
  		  </row>
  		  <row>
  		    <entry><para><computeroutput>Standard Deviation</computeroutput></para></entry>
! 		    <entry><para>Standard devation of results</para></entry>
  		    <entry><para><literal>microseconds</literal></para></entry>
  		  <row>
--- 268,277 ----
  		  <row>
  		    <entry><para><computeroutput>Max</computeroutput></para></entry>
! 		    <entry><para>Maximum latency</para></entry>
  		    <entry><para><literal>microseconds</literal></para></entry>
  		  </row>
  		  <row>
  		    <entry><para><computeroutput>Standard Deviation</computeroutput></para></entry>
! 		    <entry><para>Standard deviation of results</para></entry>
  		    <entry><para><literal>microseconds</literal></para></entry>
  		  <row>
***************
*** 281,285 ****
  
        <sect1 id="tbench-about"><title>About</title> <para>The Tbench
! 	test is an implementation of Andrew Trdigells Tbench test.
  	The test simulates a heavy load on a Samba server; but instead
  	of the target machine going to the disk it simply echos the
--- 293,297 ----
  
        <sect1 id="tbench-about"><title>About</title> <para>The Tbench
! 	test is an implementation of Andrew Tridgell's Tbench test.
  	The test simulates a heavy load on a Samba server; but instead
  	of the target machine going to the disk it simply echos the
***************
*** 293,297 ****
  	<literal>ipbenchd</literal>.  The target machine has some work
  	to do with this test, so will need to be running the
! 	<command>ipbenchtd</command> daemon.</para>
  	</sect2>
  
--- 305,309 ----
  	<literal>ipbenchd</literal>.  The target machine has some work
  	to do with this test, so will need to be running the
! 	<command>ipbenchd</command> daemon.</para>
  	</sect2>
  
***************
*** 303,308 ****
  	    <para> There are a number of options that can be passed to
  	  the test.  The options should be passed with the <userinput>--test-args</userinput>
! 	  command line paramater in a simple
! 	  <userinput>"command=value,command1=value1"</userinput> format (note no whitespace).
  	  The test options are </para>
  
--- 315,320 ----
  	    <para> There are a number of options that can be passed to
  	  the test.  The options should be passed with the <userinput>--test-args</userinput>
! 	  command line parameter in a simple
! 	  <userinput>"command=value,command1=value1"</userinput> format (note no white-space).
  	  The test options are </para>
  
***************
*** 333,337 ****
  	  
  	  <sect3><title>Test output</title> <para>The output of the
! 	    test is presented in Mbps of acheived throughput.
  	  </sect3>
  	  
--- 345,349 ----
  	  
  	  <sect3><title>Test output</title> <para>The output of the
! 	    test is presented in Mbps of achieved throughput.
  	  </sect3>
  	  
***************
*** 340,345 ****
  
      </chapter>
    </part>
-   
-   
  </book>
\ No newline at end of file
--- 352,535 ----
  
      </chapter>
+     <chapter id="nfslatency"><title>NFS Latency</title>
+       <sect1 id="nfslatency-about"><title>About</title>
+ 	<para>The NFS Latency test is way to measure NFS performance.
+ 	It is not a full NFS performance suite, but allows measurement
+ 	of reads per second from an NFS server.</para>
+       </sect1>
+       <sect1 id="nfslatency-running"><title>Running the NFS Latency
+ test</title>
+ 	<sect2><title>Setting up the server and clients</title>
+ 	  <para>
+ 	    To run this test the target must export a filesystem (or
+ 	    part of one) to all the clients.  If you don't want to run
+             <command>ipbenchd</command> as root on the clients, you
+ 	    will need to give the <command>insecure</command> option
+ 	    to <command>exportfs</command>.
+ 	  </para>
+ 	  <para>
+ 	    Assuming that your test network is 192.168.0.0/24, your
+ 	    <command>/etc/exports</command> file could comtain:
+ 	    <literal>
+ 		/tmp	192.168.0.0/24(insecure,async,rw)
+ 	    </literal>
+ 	  </para>
+ 	  <para>
+ 	  Create a file in the exported directory somewhere:
+ 	  <userinput>
+ 		> /tmp/nfstestfile
+ 		chmod a=rw /tmp/nfstestfile
+ 	  </userinput>
+ 	  </para>
+ 	  <para>You should check that the clients can mount and
+ 	  unmount the directory, as <literal>ipbench</literal> does
+ 	  not always give useful error messages.
+ 	  </para>
+ 	</sect2>
+ 	<sect2><title>Running the test</title>
+ 	  <para>
+ 		You need to know the name or IP address of the target
+ 		on the test network, the name of the exported
+ 		directory, and the name of the file on that directory.
+ 	</para>
+ 	  <para>
+ 	  The test options are </para>
+ 
+ 	    <table frame='all'><title>nfs_latency Test Options</title>
+ 	      <tgroup cols='5' align='left' colsep='1' rowsep='1'>
+ 		<thead>
+ 		  <row>
+ 		    <entry>Argument</entry>
+ 		    <entry>Description</entry>
+ 		    <entry>Example</entry>
+ 		    <entry>Default</entry>
+ 		    <entry>Notes</entry>
+ 		  </row>		 
+ 		</thead>
+ 	      <tbody>
+ 		<row>
+ 		  <entry><userinput>path</userinput></entry>
+ 		  <entry><para>Name of exported directory, as in
+ 			<literal>/etc/exports</literal> on the
+ 			target</para></entry> 
+ 		  <entry><para><userinput>path=/tmp</userinput></para></entry>
+ 		  <entry><para><userinput>/tmp</userinput></para></entry>
+ 		  <entry></entry>
+ 		</row>
+ 		<row>
+ 		  <entry><userinput>filename</userinput></entry>
+ 		  <entry><para>Name of a file relative to
+ <literal>path</literal></para></entry>
+ 		  <entry><userinput>filename=foo/bah</userinput></entry>
+ 		  <entry><userinput>file.bench</userinput></entry>
+ 		  <entry><para>In early versions of
+ <literal>ipbench</literal> the filename could not contain slashes.</para></entry>
+ 		</row>
+ 		<row>
+ 		  <entry><userinput>rate</userinput></entry>
+ 		  <entry><para>Requested operations per
+ second.</para></entry>
+ 		  <entry><userinput>rate=1000</userinput></entry>
+ 		  <entry>10000</entry>
+ 		  <entry></entry>
+ 		</row>
+ 	      </tbody>
+ 	    </tgroup>
+ 	  </table>
+ 	</sect2>
+ 	<sect2><title>Example</title>
+ 	  <para>
+ 	<userinput>
+ 	ipbench --client=tinny3 --client=tinny4 \
+ --test-args=path=/,filename=tmp/bench.file --test=nfs_latency
+ --test-target=192.168.0.5
+ </userinput>
+ <literal>
+ #Achieved request rate,Achieved reply rate,Min latency,Average latency,Median latency,Max latency,Samples,Min runtime,Average runtime,Median runtime,Max runtime
+ 19999,6212,414,640020,664212,706549,400000,63175592,64383842,65592092,65592092
+ </literal>
+ 
+ Output is a comma-separated set of fields, with times in microseconds.
+ <table frame='all'><title>nfs_latency output fields</title>
+ 	      <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ 		<thead>
+ 		  <row>
+ 		    <entry>Field</entry>
+ 		    <entry>Units</entry>
+ 		    <entry>Description</entry>
+ 		  </row>
+ 		</thead>
+ 		<tbody>
+ 		  <row>
+ 		    <entry>Achieved rate</entry>
+ 		    <entry>operations per second</entry>
+ 		    <entry><para>Achieved rate aggregated across all
+ the clients.  This may differ from the requested rate if too high a
+ rate is requested, and the clients can't keep up.</para></entry>
+ 		  </row>
+ 		  <row><entry>Reply rate</entry>
+ 		    <entry>operations/sec</entry>
+ 		    <entry>Read replies per second from the target</entry>
+ 		  </row>
+ 		  <row>
+ 		    <entry>Minimum Latency</entry>
+ 		    <entry>microseconds</entry>
+ 		    <entry><para>the fastest time for a reply from an RPC
+ 			read request.</para></entry>
+ 		  </row>
+ 		  <row>
+ 		    <entry>Mean Latency</entry>
+ 		    <entry>microseconds </entry>
+ 		    <entry></entry>
+ 		  </row>
+ 		  <row>
+ 		    <entry>Median Latency</entry>
+ 		    <entry>microseconds </entry>
+ 		    <entry></entry>
+ 		  </row>
+ 		  <row>
+ 		    <entry>maximum latency Latency</entry>
+ 		    <entry>microseconds </entry>
+ 		    <entry></entry>
+ 		  </row>
+ 		  <row>
+ 		    <entry>samples</entry>
+ 		    <entry>read rpcs</entry>
+ 		    <entry><para> the number of replies sampled to
+ generate the latency averages</para></entry>
+ 		  </row>
+ 		  <row>
+ 		    <entry>Min Runtime</entry>
+ 		    <entry>microseconds</entry>
+ 		    <entry>The minimum time taken to perform 20000
+ read/writes, across all clients</entry>
+ 		  </row>
+ 		  <row><entry>mean runtime</entry>
+ 		    <entry>
+ 		    <entry>microseconds</entry>
+ 		    <entry>The average time taken to perform 20000
+ read/writes, across all clients</entry>
+ 		  </row>
+ 		  <row><entry>median runtime</entry>
+ 		    <entry>
+ 		    <entry>microseconds</entry>
+ 		    <entry>A different average time taken to perform 20000
+ read/writes, across all clients</entry>
+ 		  </row>
+ 		  <row><entry>maximum runtime</entry>
+ 		    <entry>
+ 		    <entry>microseconds</entry>
+ 		    <entry>The maximum time taken to perform 20000
+ read/writes, across all clients</entry>
+ 		  </row>
+ 		</tbody>
+ 	      </tgroup>
+ 	    </table>
+ <para>
+ For sanity, you should check that the runtimes are all very similar,
+ and that the achieved request rate is what you asked for.</para>
+ 	</sect2>
+       </sect1>
+     </chapter>
    </part>
  </book>
\ No newline at end of file