[netperf-dev] netperf2 commit notice r396 - in trunk/doc: . examples
raj at netperf.org
raj at netperf.org
Thu Jun 23 17:15:15 PDT 2011
Author: raj
Date: 2011-06-23 17:15:14 -0700 (Thu, 23 Jun 2011)
New Revision: 396
Added:
trunk/doc/examples/netperf_interim_to_rrd.sh
Modified:
trunk/doc/netperf.html
trunk/doc/netperf.info
trunk/doc/netperf.pdf
trunk/doc/netperf.texi
trunk/doc/netperf.xml
Log:
more doc updates
Added: trunk/doc/examples/netperf_interim_to_rrd.sh
===================================================================
--- trunk/doc/examples/netperf_interim_to_rrd.sh (rev 0)
+++ trunk/doc/examples/netperf_interim_to_rrd.sh 2011-06-24 00:15:14 UTC (rev 396)
@@ -0,0 +1,145 @@
+
+# set -x
+SAMPLE_TIMES="2 5 10 20 30 45 60"
+SAMPLE_TIMES="60 45 30 20 10 5 2"
+FLOW_RATES="0 200 2000 20000 200000"
+NETPERF="/home/raj/netperf2_trunk/src/netperf"
+
+# these will be switch-specific
+CPMIB="SFLOW-MIB::sFlowCpInterval.11.1.3.6.1.2.1.2.2.1.1.27.1"
+FSMIB="SFLOW-MIB::sFlowFsPacketSamplingRate.11.1.3.6.1.2.1.2.2.1.1.27.1"
+SFLOW_RRD="/tmp/counters/192.168.1.1/1/27/generic.rrd"
+
+for sample in $SAMPLE_TIMES
+do
+
+ LENGTH="300"
+ XGRID="--x-grid SECOND:5:SECOND:30:SECOND:30:0:%X"
+ # we want at least 10 sFlow samples
+ SAMPLES=`expr $LENGTH / $sample`
+ if [ $SAMPLES -lt 10 ]; then
+ LENGTH=`expr 10 \* $sample`
+ XGRID="--x-grid SECOND:10:SECOND:60:SECOND:60:0:%X"
+ fi
+
+ # configure the switch for the counter sampling interval
+ snmpset 192.168.1.1 $CPMIB i $sample
+ TWOXSAMPLE=`expr $sample \* 2`
+ for flow in $FLOW_RATES
+ do
+ # configure the switch for the flow sampling rate which is one per
+ # N on average, with some randomization if adhering to the sFlow
+ # spec.
+ snmpset 192.168.1.1 $FSMIB i $flow
+
+ # setup some variables
+ FILE_BASE="sample_${sample}_flow_${flow}"
+ NETPERF_BASE="raw_netperf_${FILE_BASE}"
+ NETPERF_RAW="${NETPERF_BASE}.out"
+ NETPERF_RRD="${NETPERF_BASE}.rrd"
+
+ # provide an indication of forward progress and status
+ echo "sample rate $sample flow rate 1 in $flow"
+
+ # start top
+ top -b -i > "top_${FILE_BASE}.out" &
+ TOP_PID=$!
+
+ # run our netperf test long enough to make sure we have as many
+ # sFlow samples as we wish even after we later skip the first two.
+ $NETPERF -t UDP_STREAM -H 192.168.1.3 -l `expr $LENGTH + $TWOXSAMPLE`\
+ -D 1 -c -C -- -m 1472 -s 64K -S 64K > $NETPERF_RAW
+
+ # stop top
+ kill -HUP $TOP_PID
+
+ # prepare to shove the interim results into an RRD
+ grep Interim $NETPERF_RAW > interims.tmp
+
+ # over what time interval do we have netperf interim results?
+ START=`head -1 interims.tmp | awk '{printf("%d",$10)}'`
+ END=`tail -1 interims.tmp | awk '{printf("%d",$10)}'`
+
+ # create an rrd for netperf starting at the beginning of that interval
+ rrdtool create netperf.rrd --step 1 --start $START \
+ DS:mbps:GAUGE:2:U:U RRA:AVERAGE:0.5:1:${LENGTH}
+
+ # shove those interim results into the netperf rrd
+ awk '{printf("rrdtool update netperf.rrd %f:%f\n",$10,$3)}' \
+ interims.tmp | sh
+ mv netperf.rrd $NETPERF_RRD
+
+ # extract the data from the sflow rrd to save it for posterity
+ rrdtool fetch $SFLOW_RRD AVERAGE --start $START --end $END \
+ > sflow_${FILE_BASE}.fetch
+
+ # now make the graph, trim-off the first two sFlow counter samples
+ # for better automagic scaling. the magic multiplier is how to go
+ # from mbps from netperf, which counts only payload, to octets on
+ # the wire assuming 8 bytes of UDP header 20 bytes of IP, 14 bytes
+ # of ethernet, 4 bytes of FCS and 1472 bytes of user payload
+ START=`expr $START + $TWOXSAMPLE`
+
+ # we don't like rrdtool's autoscaling
+ YMIN=`rrdtool graph /dev/null --start $START --end $END \
+ DEF:foo=${SFLOW_RRD}:ifOutOctets:AVERAGE \
+ CDEF:bar=foo,0.98,\* \
+ VDEF:bing=bar,MINIMUM \
+ PRINT:bing:"%6.2lf" | sed 1d`
+
+ YMAX=`rrdtool graph /dev/null --start $START --end $END \
+ DEF:foo=${SFLOW_RRD}:ifOutOctets:AVERAGE \
+ CDEF:bar=foo,1.02,\* \
+ VDEF:bing=bar,MAXIMUM \
+ PRINT:bing:"%6.2lf" | sed 1d`
+
+ # also consider the neterf results
+ NMIN=`rrdtool graph /dev/null --start $START --end $END \
+ DEF:foo=${NETPERF_RRD}:mbps:AVERAGE \
+ CDEF:baz=foo,128906.25,\* \
+ CDEF:bar=baz,0.98,\* \
+ VDEF:bing=bar,MINIMUM \
+ PRINT:bing:"%6.2lf" | sed 1d`
+
+ NMAX=`rrdtool graph /dev/null --start $START --end $END \
+ DEF:foo=${NETPERF_RRD}:mbps:AVERAGE \
+ CDEF:baz=foo,128906.25,\* \
+ CDEF:bar=baz,1.02,\* \
+ VDEF:bing=bar,MAXIMUM \
+ PRINT:bing:"%6.2lf" | sed 1d`
+
+ # I am certain someone will say dude use perl when they see this
+ INMIN=`echo $NMIN | awk '{printf("%d",$1)}'`
+ INMAX=`echo $NMAX | awk '{printf("%d",$1)}'`
+ IYMIN=`echo $YMIN | awk '{printf("%d",$1)}'`
+ IYMAX=`echo $YMAX | awk '{printf("%d",$1)}'`
+
+ # we wont sweat the fractional part
+ if [ $INMIN -lt $IYMIN ]; then
+ YMIN=$NMIN
+ fi
+
+ if [ $INMAX -gt $IYMAX ]; then
+ YMAX=$NMAX
+ fi
+
+ GRAPH="graph_${FILE_BASE}.svg"
+ SIZE="-w 1000 -h 400"
+ rrdtool graph $GRAPH --start $START --end $END \
+ --imgformat SVG \
+ -t "sFlow counter accuracy, average flow sample rate 1 in ${flow}" \
+ -v "Octets/s" \
+ $XGRID $SIZE --full-size-mode \
+ --upper-limit $YMAX \
+ --lower-limit $YMIN \
+ --rigid \
+ --alt-y-grid \
+ DEF:foo=${NETPERF_RRD}:mbps:AVERAGE \
+ DEF:bar=${SFLOW_RRD}:ifOutOctets:AVERAGE \
+ CDEF:baz=foo,128906.25,\* \
+ HRULE:124019607.84#000000:"Theoretical link-rate" \
+ LINE2:baz#FF0000:"netperf+headers at 1s intvl" \
+ LINE2:bar#00FF0080:"sFlow counters at ${sample}s intvl"
+ done
+done
+
Property changes on: trunk/doc/examples/netperf_interim_to_rrd.sh
___________________________________________________________________
Added: svn:executable
+ *
Modified: trunk/doc/netperf.html
===================================================================
--- trunk/doc/netperf.html 2011-06-23 01:13:29 UTC (rev 395)
+++ trunk/doc/netperf.html 2011-06-24 00:15:14 UTC (rev 396)
@@ -49,7 +49,10 @@
<li><a name="toc_The-Design-of-Netperf" href="#The-Design-of-Netperf">3 The Design of Netperf</a>
<ul>
<li><a href="#CPU-Utilization">3.1 CPU Utilization</a>
+<ul>
+<li><a href="#CPU-Utilization-in-a-Virtual-Guest">3.1.1 CPU Utilization in a Virtual Guest</a>
</li></ul>
+</li></ul>
<li><a name="toc_Global-Command_002dline-Options" href="#Global-Command_002dline-Options">4 Global Command-line Options</a>
<ul>
<li><a href="#Command_002dline-Options-Syntax">4.1 Command-line Options Syntax</a>
@@ -101,13 +104,19 @@
<li><a href="#Bidirectional-Transfer-with-Concurrent-Tests">8.1 Bidirectional Transfer with Concurrent Tests</a>
<li><a href="#Bidirectional-Transfer-with-TCP_005fRR">8.2 Bidirectional Transfer with TCP_RR</a>
</li></ul>
-<li><a name="toc_Other-Netperf-Tests" href="#Other-Netperf-Tests">9 Other Netperf Tests</a>
+<li><a name="toc_The-Omni-Tests" href="#The-Omni-Tests">9 The Omni Tests</a>
<ul>
-<li><a href="#CPU-rate-calibration">9.1 CPU rate calibration</a>
+<li><a href="#Native-Omni-Tests">9.1 Native Omni Tests</a>
+<li><a href="#Migrated-Tests">9.2 Migrated Tests</a>
+<li><a href="#Omni-Output-Selection">9.3 Omni Output Selection</a>
</li></ul>
-<li><a name="toc_Address-Resolution" href="#Address-Resolution">10 Address Resolution</a>
-<li><a name="toc_Enhancing-Netperf" href="#Enhancing-Netperf">11 Enhancing Netperf</a>
-<li><a name="toc_Netperf4" href="#Netperf4">12 Netperf4</a>
+<li><a name="toc_Other-Netperf-Tests" href="#Other-Netperf-Tests">10 Other Netperf Tests</a>
+<ul>
+<li><a href="#CPU-rate-calibration">10.1 CPU rate calibration</a>
+</li></ul>
+<li><a name="toc_Address-Resolution" href="#Address-Resolution">11 Address Resolution</a>
+<li><a name="toc_Enhancing-Netperf" href="#Enhancing-Netperf">12 Enhancing Netperf</a>
+<li><a name="toc_Netperf4" href="#Netperf4">13 Netperf4</a>
<li><a name="toc_Concept-Index" href="#Concept-Index">Concept Index</a>
<li><a name="toc_Option-Index" href="#Option-Index">Option Index</a>
</li></ul>
@@ -145,121 +154,15 @@
<li><a accesskey="6" href="#Using-Netperf-to-Measure-Request_002fResponse">Using Netperf to Measure Request/Response </a>
<li><a accesskey="7" href="#Using-Netperf-to-Measure-Aggregate-Performance">Using Netperf to Measure Aggregate Performance</a>
<li><a accesskey="8" href="#Using-Netperf-to-Measure-Bidirectional-Transfer">Using Netperf to Measure Bidirectional Transfer</a>
-<li><a accesskey="9" href="#Other-Netperf-Tests">Other Netperf Tests</a>
+<li><a accesskey="9" href="#The-Omni-Tests">The Omni Tests</a>
+<li><a href="#Other-Netperf-Tests">Other Netperf Tests</a>
<li><a href="#Address-Resolution">Address Resolution</a>
<li><a href="#Enhancing-Netperf">Enhancing Netperf</a>
<li><a href="#Netperf4">Netperf4</a>
<li><a href="#Concept-Index">Concept Index</a>
<li><a href="#Option-Index">Option Index</a>
+</ul>
-</li></ul>
-<p>--- The Detailed Node Listing ---
-
-<p>Introduction
-
-</p>
-<ul class="menu">
-<li><a href="#Conventions">Conventions</a>
-
-</li></ul>
-<p>Installing Netperf
-
-</p>
-<ul class="menu">
-<li><a href="#Getting-Netperf-Bits">Getting Netperf Bits</a>
-<li><a href="#Installing-Netperf-Bits">Installing Netperf Bits</a>
-<li><a href="#Verifying-Installation">Verifying Installation</a>
-
-</li></ul>
-<p>The Design of Netperf
-
-</p>
-<ul class="menu">
-<li><a href="#CPU-Utilization">CPU Utilization</a>
-
-</li></ul>
-<p>Global Command-line Options
-
-</p>
-<ul class="menu">
-<li><a href="#Command_002dline-Options-Syntax">Command-line Options Syntax</a>
-<li><a href="#Global-Options">Global Options</a>
-
-</li></ul>
-<p>Using Netperf to Measure Bulk Data Transfer
-
-</p>
-<ul class="menu">
-<li><a href="#Issues-in-Bulk-Transfer">Issues in Bulk Transfer</a>
-<li><a href="#Options-common-to-TCP-UDP-and-SCTP-tests">Options common to TCP UDP and SCTP tests</a>
-
-</li></ul>
-<p>Options common to TCP UDP and SCTP tests
-
-</p>
-<ul class="menu">
-<li><a href="#TCP_005fSTREAM">TCP_STREAM</a>
-<li><a href="#TCP_005fMAERTS">TCP_MAERTS</a>
-<li><a href="#TCP_005fSENDFILE">TCP_SENDFILE</a>
-<li><a href="#UDP_005fSTREAM">UDP_STREAM</a>
-<li><a href="#XTI_005fTCP_005fSTREAM">XTI_TCP_STREAM</a>
-<li><a href="#XTI_005fUDP_005fSTREAM">XTI_UDP_STREAM</a>
-<li><a href="#SCTP_005fSTREAM">SCTP_STREAM</a>
-<li><a href="#DLCO_005fSTREAM">DLCO_STREAM</a>
-<li><a href="#DLCL_005fSTREAM">DLCL_STREAM</a>
-<li><a href="#STREAM_005fSTREAM">STREAM_STREAM</a>
-<li><a href="#DG_005fSTREAM">DG_STREAM</a>
-
-</li></ul>
-<p>Using Netperf to Measure Request/Response
-
-</p>
-<ul class="menu">
-<li><a href="#Issues-in-Request_002fResponse">Issues in Request/Response</a>
-<li><a href="#Options-Common-to-TCP-UDP-and-SCTP-_005fRR-tests">Options Common to TCP UDP and SCTP _RR tests</a>
-
-</li></ul>
-<p>Options Common to TCP UDP and SCTP _RR tests
-
-</p>
-<ul class="menu">
-<li><a href="#TCP_005fRR">TCP_RR</a>
-<li><a href="#TCP_005fCC">TCP_CC</a>
-<li><a href="#TCP_005fCRR">TCP_CRR</a>
-<li><a href="#UDP_005fRR">UDP_RR</a>
-<li><a href="#XTI_005fTCP_005fRR">XTI_TCP_RR</a>
-<li><a href="#XTI_005fTCP_005fCC">XTI_TCP_CC</a>
-<li><a href="#XTI_005fTCP_005fCRR">XTI_TCP_CRR</a>
-<li><a href="#XTI_005fUDP_005fRR">XTI_UDP_RR</a>
-<li><a href="#DLCL_005fRR">DLCL_RR</a>
-<li><a href="#DLCO_005fRR">DLCO_RR</a>
-<li><a href="#SCTP_005fRR">SCTP_RR</a>
-
-</li></ul>
-<p>Using Netperf to Measure Aggregate Performance
-
-</p>
-<ul class="menu">
-<li><a href="#Running-Concurrent-Netperf-Tests">Running Concurrent Netperf Tests</a>
-<li><a href="#Using-_002d_002denable_002dburst">Using --enable-burst</a>
-
-</li></ul>
-<p>Using Netperf to Measure Bidirectional Transfer
-
-</p>
-<ul class="menu">
-<li><a href="#Bidirectional-Transfer-with-Concurrent-Tests">Bidirectional Transfer with Concurrent Tests</a>
-<li><a href="#Bidirectional-Transfer-with-TCP_005fRR">Bidirectional Transfer with TCP_RR</a>
-
-</li></ul>
-<p>Other Netperf Tests
-
-</p>
-<ul class="menu">
-<li><a href="#CPU-rate-calibration">CPU rate calibration</a>
-
- </ul>
-
<div class="node">
<a name="Introduction"></a>
<p><hr>
@@ -682,14 +585,16 @@
Netperf is designed around a basic client-server model. There are
two executables - netperf and netserver. Generally you will only
execute the netperf program, with the netserver program being invoked
-by the remote system's inetd or equivalent.
-When you execute netperf, the first that that will happen is the
-establishment of a control connection to the remote system. This
-connection will be used to pass test configuration information and
-results to and from the remote system. Regardless of the type of test
-to be run, the control connection will be a TCP connection using BSD
-sockets. The control connection can use either IPv4 or IPv6.
+by the remote system's inetd or having been previously started as its
+own standalone daemon.
+ <p>When you execute netperf it will establish a “control connection” to
+the remote system. This connection will be used to pass test
+configuration information and results to and from the remote system.
+Regardless of the type of test to be run, the control connection will
+be a TCP connection using BSD sockets. The control connection can use
+either IPv4 or IPv6.
+
<p>Once the control connection is up and the configuration information
has been passed, a separate “data” connection will be opened for the
measurement itself using the API's and protocols appropriate for the
@@ -721,9 +626,10 @@
<p><a name="index-CPU-Utilization-14"></a>
CPU utilization is an important, and alas all-too infrequently
reported component of networking performance. Unfortunately, it can
-be one of the most difficult metrics to measure accurately as many
-systems offer mechanisms that are at best il-suited to measuring CPU
-utilization in high interrupt rate (eg networking) situations.
+be one of the most difficult metrics to measure accurately and
+portably. Netperf will do its level best to report accurate
+CPU utilization figures, but some combinations of processor, OS and
+configuration may make that difficult.
<p>CPU utilization in netperf is reported as a value between 0 and 100%
regardless of the number of CPUs involved. In addition to CPU
@@ -737,7 +643,8 @@
<p>Service demand can be particularly useful when trying to gauge the
effect of a performance change. It is essentially a measure of
-efficiency, with smaller values being more efficient.
+efficiency, with smaller values being more efficient and thus
+“better.”
<p>Netperf is coded to be able to use one of several, generally
platform-specific CPU utilization measurement mechanisms. Single
@@ -766,20 +673,20 @@
overhead. This mechanism required calibration.
<br><dt><code>P</code><dd>An HP-UX-specific CPU utilization mechanism whereby the kernel
keeps-track of time (in the form of CPU cycles) spent in the kernel
-idle loop (HP-UX 10.0 to 11.23 inclusive), or where the kernel keeps
+idle loop (HP-UX 10.0 to 11.31 inclusive), or where the kernel keeps
track of time spent in idle, user, kernel and interrupt processing
(HP-UX 11.23 and later). The former requires calibration, the latter
does not. Values in either case are retrieved via one of the pstat(2)
family of calls, hence the use of the letter <code>P</code>. The code for
these mechanisms is found in <samp><span class="file">src/netcpu_pstat.c</span></samp> and
<samp><span class="file">src/netcpu_pstatnew.c</span></samp> respectively.
-<br><dt><code>K</code><dd>A Solaris-specific CPU utilization mechanism where by the kernel
-keeps track of ticks (eg HZ) spent in the idle loop. This method is
+<br><dt><code>K</code><dd>A Solaris-specific CPU utilization mechanism whereby the kernel keeps
+track of ticks (eg HZ) spent in the idle loop. This method is
statistical and is known to be inaccurate when the interrupt rate is
above epsilon as time spent processing interrupts is not subtracted
from idle. The value is retrieved via a kstat() call - hence the use
of the letter <code>K</code>. Since this mechanism uses units of ticks (HZ)
-the calibration value should invariably match HZ. (Eg 100) The code
+the calibration value should invariably match HZ. (Eg 100) The code
for this mechanism is implemented in <samp><span class="file">src/netcpu_kstat.c</span></samp>.
<br><dt><code>M</code><dd>A Solaris-specific mechanism available on Solaris 10 and latter which
uses the new microstate accounting mechanisms. There are two, alas,
@@ -804,8 +711,8 @@
what appears to be a form of micro-state accounting and requires no
calibration. On laptops, or other systems which may dynamically alter
the CPU frequency to minimize power consumtion, it has been suggested
-that this mechanism may become slightly confsed, in which case using
-BIOS settings to disable the power saving would be indicated.
+that this mechanism may become slightly confused, in which case using
+BIOS/uEFI settings to disable the power saving would be indicated.
<br><dt><code>S</code><dd>This mechanism uses <samp><span class="file">/proc/stat</span></samp> on Linux to retrieve time
(ticks) spent in idle mode. It is thought but not known to be
@@ -817,7 +724,7 @@
<br><dt><code>Others</code><dd>Other mechanisms included in netperf in the past have included using
the times() and getrusage() calls. These calls are actually rather
poorly suited to the task of measuring CPU overhead for networking as
-they tend to be process-specific and much network-related processing
+they tend to be process-specific and much network-related processing
can happen outside the context of a process, in places where it is not
a given it will be charged to the correct, or even a process. They
are mentioned here as a warning to anyone seeing those mechanisms used
@@ -859,7 +766,36 @@
with other mechanisms. However, platform tools such as top, vmstat or
mpstat are often based on the same mechanisms used by netperf.
+<ul class="menu">
+<li><a accesskey="1" href="#CPU-Utilization-in-a-Virtual-Guest">CPU Utilization in a Virtual Guest</a>
+</ul>
+
<div class="node">
+<a name="CPU-Utilization-in-a-Virtual-Guest"></a>
+<p><hr>
+Previous: <a rel="previous" accesskey="p" href="#CPU-Utilization">CPU Utilization</a>,
+Up: <a rel="up" accesskey="u" href="#CPU-Utilization">CPU Utilization</a>
+
+</div>
+
+<h4 class="subsection">3.1.1 CPU Utilization in a Virtual Guest</h4>
+
+<p>The CPU utilization mechanisms used by netperf are “inline” in that
+they are run by the same netperf or netserver process as is running
+the test itself. This works just fine for “bare iron” tests but
+runs into a problem when using virtual machines.
+
+ <p>A virtual guest can be thought of as being similar to a process in a
+bare iron system. As such, any CPU utilization mechanisms used in the
+virtual guest are similar to “process-local” mechanisms in a bare
+iron situation. However, just as with bare iron, much networking
+processing happens outside the context of the virtual guest. It takes
+place in the hypervisor, and is not visible to mechanisms running in
+the guest(s). For this reason, one should not really trust CPU
+utilization figures reported by netperf or netserver when running in a
+virtual guest.
+
+<div class="node">
<a name="Global-Command-line-Options"></a>
<a name="Global-Command_002dline-Options"></a>
<p><hr>
@@ -2859,7 +2795,7 @@
<div class="node">
<a name="Using-Netperf-to-Measure-Bidirectional-Transfer"></a>
<p><hr>
-Next: <a rel="next" accesskey="n" href="#Other-Netperf-Tests">Other Netperf Tests</a>,
+Next: <a rel="next" accesskey="n" href="#The-Omni-Tests">The Omni Tests</a>,
Previous: <a rel="previous" accesskey="p" href="#Using-Netperf-to-Measure-Aggregate-Performance">Using Netperf to Measure Aggregate Performance</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
@@ -2989,15 +2925,231 @@
verbosity of 2 or more with the global <samp><span class="option">-v</span></samp> option.
<div class="node">
+<a name="The-Omni-Tests"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#Other-Netperf-Tests">Other Netperf Tests</a>,
+Previous: <a rel="previous" accesskey="p" href="#Using-Netperf-to-Measure-Bidirectional-Transfer">Using Netperf to Measure Bidirectional Transfer</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</div>
+
+<h2 class="chapter">9 The Omni Tests</h2>
+
+<p>Beginning with version 2.5.0, netperf begins a migration to the
+“omni” tests or “Two routines to measure them all.” The code for
+the omni tests can be found in <samp><span class="file">src/nettest_omni.c</span></samp> and the goal
+is to make it easier for netperf to support multiple protocols and
+report a great many additional things about the systems under test.
+Additionally, a flexible output selection mechanism is present which
+allows the user to chose specifically what values she wishes to have
+reported and in what format.
+
+ <p>The omni tests are included by default in version 2.5.0. To disable
+them, one must:
+<pre class="example"> ./configure --enable-omni=no ...
+</pre>
+ <p>and remake netperf. Remaking netserver is optional because even in
+2.5.0 it has “unmigrated” netserver side routines for the classic
+(eg <samp><span class="file">src/nettest_bsd.c</span></samp>) tests.
+
+<ul class="menu">
+<li><a accesskey="1" href="#Native-Omni-Tests">Native Omni Tests</a>
+<li><a accesskey="2" href="#Migrated-Tests">Migrated Tests</a>
+<li><a accesskey="3" href="#Omni-Output-Selection">Omni Output Selection</a>
+</ul>
+
+<div class="node">
+<a name="Native-Omni-Tests"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#Migrated-Tests">Migrated Tests</a>,
+Previous: <a rel="previous" accesskey="p" href="#The-Omni-Tests">The Omni Tests</a>,
+Up: <a rel="up" accesskey="u" href="#The-Omni-Tests">The Omni Tests</a>
+
+</div>
+
+<h3 class="section">9.1 Native Omni Tests</h3>
+
+<p>One access the omni tests “natively” by using a value of “OMNI”
+with the global <samp><span class="option">-t</span></samp> test-selection option. This will then
+cause netperf to use the code in <samp><span class="file">src/nettest_omni.c</span></samp> and in
+particular the test-specific options parser for the omni tests. The
+test-specific options for the omni tests are a superset of those for
+“classic” tests. The options added by the omni tests are:
+
+
+<a name="index-g_t_002dc_002c-Test_002dspecific-84"></a>
+<dl><dt><code>-c</code><dd>This explicitly declares that the test is to include connection
+establishment and tear-down as in either a TCP_CRR or TCP_CC test.
+
+ <p><a name="index-g_t_002dd_002c-Test_002dspecific-85"></a><br><dt><code>-d <direction></code><dd>This option sets the direction of the test relative to the netperf
+process. As of version 2.5.0 one can use:
+
+ <dl>
+<dt><code>send, xmit or 2</code><dd>Any of which will cause netperf to send to the netserver.
+<br><dt><code>recv, receive or 4</code><dd>Any of which will cause netserver to send to netperf.
+<br><dt><code>rr or 6</code><dd>Either of which will cause a request/response test.
+</dl>
+
+ <p><a name="index-g_t_002dk_002c-Test_002dspecific-86"></a><br><dt><code>-k <output selector></code><dd>This option sets the style of output to “keyval” where each line of
+output has the form:
+ <pre class="example"> key=value
+</pre>
+ <p>For example:
+ <pre class="example"> $ netperf -t omni -- -d rr -k "THROUGHPUT,THROUGHPUT_UNITS"
+ OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ THROUGHPUT=59092.65
+ THROUGHPUT_UNITS=Trans/s
+</pre>
+ <p>Using the <samp><span class="option">-k</span></samp> option will override any previous, test-specific
+<samp><span class="option">-o</span></samp> or <samp><span class="option">-O</span></samp> option.
+
+ <p><a name="index-g_t_002do_002c-Test_002dspecific-87"></a><br><dt><code>-o <output selector></code><dd>This option sets the style of output to “CSV” where there will be
+one line of comma-separated values, preceeded by one line of column
+names unless the global <samp><span class="option">-P</span></samp> option is used with a value of 0:
+ <pre class="example"> $ netperf -t omni -- -d rr -o "THROUGHPUT,THROUGHPUT_UNITS"
+ OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ Throughput,Throughput Units
+ 60999.07,Trans/s
+</pre>
+ <p>Using the <samp><span class="option">-o</span></samp> option will override any previous, test-specific
+<samp><span class="option">-k</span></samp> or <samp><span class="option">-O</span></samp> option.
+
+ <p><a name="index-g_t_002dO_002c-Test_002dspecific-88"></a><br><dt><code>-O <output selector></code><dd>This option sets the style of output to “human readable” which will
+look quite similar to classic netperf output:
+ <pre class="example"> $ netperf -t omni -- -d rr -O "THROUGHPUT,THROUGHPUT_UNITS"
+ OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ Throughput Throughput
+ Units
+
+
+ 60492.57 Trans/s
+</pre>
+ <p>Using the <samp><span class="option">-O</span></samp> option will override any previous, test-specific
+<samp><span class="option">-k</span></samp> or <samp><span class="option">-o</span></samp> option.
+
+ <p><a name="index-g_t_002dT_002c-Test_002dspecific-89"></a><br><dt><code>-T <protocol></code><dd>This option is used to explicitly set the protocol used for the test.
+
+ <p>The default is implicit based on other settings.
+</dl>
+
+<div class="node">
+<a name="Migrated-Tests"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#Omni-Output-Selection">Omni Output Selection</a>,
+Previous: <a rel="previous" accesskey="p" href="#Native-Omni-Tests">Native Omni Tests</a>,
+Up: <a rel="up" accesskey="u" href="#The-Omni-Tests">The Omni Tests</a>
+
+</div>
+
+<h3 class="section">9.2 Migrated Tests</h3>
+
+<p>As of version 2.5.0 several tests have been migrated to use the omni
+code in <samp><span class="file">src/nettest_omni.c</span></samp> for the core of their testing. A
+migrated test retains all its previous output code and so should still
+“look and feel” just like a pre-2.5.0 test with one exception - the
+first line of the test banners will include the word “MIGRATED” at
+the beginning as in:
+
+<pre class="example"> $ ../src/netperf
+ MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ Recv Send Send
+ Socket Socket Message Elapsed
+ Size Size Size Time Throughput
+ bytes bytes bytes secs. 10^6bits/sec
+
+ 87380 16384 16384 10.00 27175.27
+</pre>
+ <p>The tests migrated in version 2.5.0 are:
+ <ul>
+<li>TCP_STREAM
+<li>TCP_MAERTS
+<li>TCP_RR
+<li>TCP_CRR
+<li>UDP_STREAM
+<li>UDP_RR
+</ul>
+
+ <p>It is expected that future releases will have additional tests
+migrated to use the “omni” functionality.
+
+ <p>If one uses “omni-specific” test-specific options in conjunction
+with a migrated test, instead of using the classic output code, the
+new omni output code will be used. For example if one uses the
+<samp><span class="option">-k</span></samp> test-specific option with a value of
+“MIN_LATENCY,MAX_LATENCY” with a migrated TCP_RR test one will see:
+
+<pre class="example"> $ ../src/netperf -t tcp_rr -- -k THROUGHPUT,THROUGHPUT_UNITS
+ MIGRATED TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ THROUGHPUT=60074.74
+ THROUGHPUT_UNITS=Trans/s
+</pre>
+ <p>rather than:
+<pre class="example"> $ ../src/netperf -t tcp_rr
+ MIGRATED TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ Local /Remote
+ Socket Size Request Resp. Elapsed Trans.
+ Send Recv Size Size Time Rate
+ bytes Bytes bytes bytes secs. per sec
+
+ 16384 87380 1 1 10.00 59421.52
+ 16384 87380
+</pre>
+ <div class="node">
+<a name="Omni-Output-Selection"></a>
+<p><hr>
+Previous: <a rel="previous" accesskey="p" href="#Migrated-Tests">Migrated Tests</a>,
+Up: <a rel="up" accesskey="u" href="#The-Omni-Tests">The Omni Tests</a>
+
+</div>
+
+<h3 class="section">9.3 Omni Output Selection</h3>
+
+<p>The omni test-specific <samp><span class="option">-k</span></samp>, <samp><span class="option">-o</span></samp> and <samp><span class="option">-O</span></samp>
+options take an optional <code>output selector</code> by which the user can
+configure what values are reported. The output selector can take
+several forms:
+
+ <dl>
+<dt><samp><span class="file">filename</span></samp><dd>The output selections will be read from the named file. Within the
+file there can be up to four lines of comma-separated output
+selectors. This controls how many multi-line blocks of output are emitted
+when the <samp><span class="option">-O</span></samp> option is used. This output, while not identical to
+“classic” netperf output, is inspired by it. Multiple lines have no
+effect for <samp><span class="option">-k</span></samp> and <samp><span class="option">-o</span></samp> options. Putting output
+selections in a file can be useful when the list of selections is long.
+<br><dt><code>comma and/or semi-colon-separated list</code><dd>The output selections will be parsed from a comma and/or
+semi-colon-separated list of output selectors. When the list is given
+to a <samp><span class="option">-O</span></samp> option a semi-colon specifies a new output block
+should be started. Semi-colons have the same meaning as commas when
+used with the <samp><span class="option">-k</span></samp> or <samp><span class="option">-o</span></samp> options. Depending on the
+command interpreter being used, the semi-colon may have to be escaped
+somehow to keep it from being interpreted by the command interpreter.
+This can often be done by enclosing the entire list in quotes.
+<br><dt><code>all</code><dd>If the keyword <b>all</b> is specified it means that all known output
+values should be displayed at the end of the test. This can be a
+great deal of output. As of version 2.5.0 there are 157 different
+output selectors.
+<br><dt><code>?</code><dd>If a “?” is given as the output selection, the list of all known
+output selectors will be displayed and no test actually run. When
+passed to the <samp><span class="option">-O</span></samp> option they will be listed one per
+line. Otherwise they will be listed as a comma-separated list. It may
+be necessary to protect the “?” from the command interpreter by
+escaping it or enclosing it in quotes.
+<br><dt><code>no selector</code><dd>If nothing is given to the <samp><span class="option">-k</span></samp>, <samp><span class="option">-o</span></samp> or <samp><span class="option">-O</span></samp>
+option then the code selects a default set of output selectors
+inspired by classic netperf output.
+</dl>
+
+<div class="node">
<a name="Other-Netperf-Tests"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Address-Resolution">Address Resolution</a>,
-Previous: <a rel="previous" accesskey="p" href="#Using-Netperf-to-Measure-Bidirectional-Transfer">Using Netperf to Measure Bidirectional Transfer</a>,
+Previous: <a rel="previous" accesskey="p" href="#The-Omni-Tests">The Omni Tests</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
-<h2 class="chapter">9 Other Netperf Tests</h2>
+<h2 class="chapter">10 Other Netperf Tests</h2>
<p>Apart from the typical performance tests, netperf contains some tests
which can be used to streamline measurements and reporting. These
@@ -3016,7 +3168,7 @@
</div>
-<h3 class="section">9.1 CPU rate calibration</h3>
+<h3 class="section">10.1 CPU rate calibration</h3>
<p>Some of the CPU utilization measurement mechanisms of netperf work by
comparing the rate at which some counter increments when the system is
@@ -3069,7 +3221,7 @@
</div>
<!-- node-name, next, previous, up -->
-<h2 class="chapter">10 Address Resolution</h2>
+<h2 class="chapter">11 Address Resolution</h2>
<p>Netperf versions 2.4.0 and later have merged IPv4 and IPv6 tests so
the functionality of the tests in <samp><span class="file">src/nettest_ipv6.c</span></samp> has been
@@ -3117,7 +3269,7 @@
</div>
<!-- node-name, next, previous, up -->
-<h2 class="chapter">11 Enhancing Netperf</h2>
+<h2 class="chapter">12 Enhancing Netperf</h2>
<p>Netperf is constantly evolving. If you find you want to make
enhancements to netperf, by all means do so. If you wish to add a new
@@ -3133,6 +3285,10 @@
<li>Compile and test
</ol>
+ <p>However, with the addition of the “omni” tests in version 2.5.0 it
+is preferred that one attempt to make the necessary changes to
+<samp><span class="file">src/nettest_omni.c</span></samp> rather than adding new source files.
+
<p>If you wish to submit your changes for possible inclusion into the
mainline sources, please try to base your changes on the latest
available sources. (See <a href="#Getting-Netperf-Bits">Getting Netperf Bits</a>.) and then send email
@@ -3154,7 +3310,7 @@
</div>
<!-- node-name, next, previous, up -->
-<h2 class="chapter">12 Netperf4</h2>
+<h2 class="chapter">13 Netperf4</h2>
<p>Netperf4 is the shorthand name given to version 4.X.X of netperf.
This is really a separate benchmark more than a newer version of
@@ -3244,8 +3400,10 @@
<li><a href="#index-g_t_002db_002c-Global-17"><code>-b, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dC_002c-Global-20"><code>-C, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dc_002c-Global-19"><code>-c, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
+<li><a href="#index-g_t_002dc_002c-Test_002dspecific-84"><code>-c, Test-specific</code></a>: <a href="#Native-Omni-Tests">Native Omni Tests</a></li>
<li><a href="#index-g_t_002dD_002c-Global-22"><code>-D, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dd_002c-Global-21"><code>-d, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
+<li><a href="#index-g_t_002dd_002c-Test_002dspecific-85"><code>-d, Test-specific</code></a>: <a href="#Native-Omni-Tests">Native Omni Tests</a></li>
<li><a href="#index-g_t_002dF_002c-Global-24"><code>-F, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002df_002c-Global-23"><code>-f, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dH_002c-Global-26"><code>-H, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
@@ -3256,6 +3414,7 @@
<li><a href="#index-g_t_002di_002c-Global-28"><code>-i, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dI_002c-Global-27"><code>-I, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dj_002c-Global-29"><code>-j, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
+<li><a href="#index-g_t_002dk_002c-Test_002dspecific-86"><code>-k, Test-specific</code></a>: <a href="#Native-Omni-Tests">Native Omni Tests</a></li>
<li><a href="#index-g_t_002dL_002c-Global-31"><code>-L, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dl_002c-Global-30"><code>-l, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dL_002c-Test_002dspecific-57"><code>-L, Test-specific</code></a>: <a href="#Options-Common-to-TCP-UDP-and-SCTP-_005fRR-tests">Options Common to TCP UDP and SCTP _RR tests</a></li>
@@ -3266,6 +3425,8 @@
<li><a href="#index-g_t_002dn_002c-Global-32"><code>-n, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dO_002c-Global-35"><code>-O, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002do_002c-Global-34"><code>-o, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
+<li><a href="#index-g_t_002dO_002c-Test_002dspecific-88"><code>-O, Test-specific</code></a>: <a href="#Native-Omni-Tests">Native Omni Tests</a></li>
+<li><a href="#index-g_t_002do_002c-Test_002dspecific-87"><code>-o, Test-specific</code></a>: <a href="#Native-Omni-Tests">Native Omni Tests</a></li>
<li><a href="#index-g_t_002dP_002c-Global-37"><code>-P, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dp_002c-Global-36"><code>-p, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dP_002c-Test_002dspecific-58"><code>-P, Test-specific</code></a>: <a href="#Options-Common-to-TCP-UDP-and-SCTP-_005fRR-tests">Options Common to TCP UDP and SCTP _RR tests</a></li>
@@ -3276,6 +3437,7 @@
<li><a href="#index-g_t_002ds_002c-Test_002dspecific-60"><code>-s, Test-specific</code></a>: <a href="#Options-Common-to-TCP-UDP-and-SCTP-_005fRR-tests">Options Common to TCP UDP and SCTP _RR tests</a></li>
<li><a href="#index-g_t_002ds_002c-Test_002dspecific-50"><code>-s, Test-specific</code></a>: <a href="#Options-common-to-TCP-UDP-and-SCTP-tests">Options common to TCP UDP and SCTP tests</a></li>
<li><a href="#index-g_t_002dt_002c-Global-38"><code>-t, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
+<li><a href="#index-g_t_002dT_002c-Test_002dspecific-89"><code>-T, Test-specific</code></a>: <a href="#Native-Omni-Tests">Native Omni Tests</a></li>
<li><a href="#index-g_t_002dV_002c-Global-40"><code>-V, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dv_002c-Global-39"><code>-v, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
<li><a href="#index-g_t_002dW_002c-Global-42"><code>-W, Global</code></a>: <a href="#Global-Options">Global Options</a></li>
Modified: trunk/doc/netperf.info
===================================================================
--- trunk/doc/netperf.info 2011-06-23 01:13:29 UTC (rev 395)
+++ trunk/doc/netperf.info 2011-06-24 00:15:14 UTC (rev 396)
@@ -37,6 +37,7 @@
* Using Netperf to Measure Request/Response ::
* Using Netperf to Measure Aggregate Performance::
* Using Netperf to Measure Bidirectional Transfer::
+* The Omni Tests::
* Other Netperf Tests::
* Address Resolution::
* Enhancing Netperf::
@@ -44,79 +45,6 @@
* Concept Index::
* Option Index::
- --- The Detailed Node Listing ---
-
-Introduction
-
-* Conventions::
-
-Installing Netperf
-
-* Getting Netperf Bits::
-* Installing Netperf Bits::
-* Verifying Installation::
-
-The Design of Netperf
-
-* CPU Utilization::
-
-Global Command-line Options
-
-* Command-line Options Syntax::
-* Global Options::
-
-Using Netperf to Measure Bulk Data Transfer
-
-* Issues in Bulk Transfer::
-* Options common to TCP UDP and SCTP tests::
-
-Options common to TCP UDP and SCTP tests
-
-* TCP_STREAM::
-* TCP_MAERTS::
-* TCP_SENDFILE::
-* UDP_STREAM::
-* XTI_TCP_STREAM::
-* XTI_UDP_STREAM::
-* SCTP_STREAM::
-* DLCO_STREAM::
-* DLCL_STREAM::
-* STREAM_STREAM::
-* DG_STREAM::
-
-Using Netperf to Measure Request/Response
-
-* Issues in Request/Response::
-* Options Common to TCP UDP and SCTP _RR tests::
-
-Options Common to TCP UDP and SCTP _RR tests
-
-* TCP_RR::
-* TCP_CC::
-* TCP_CRR::
-* UDP_RR::
-* XTI_TCP_RR::
-* XTI_TCP_CC::
-* XTI_TCP_CRR::
-* XTI_UDP_RR::
-* DLCL_RR::
-* DLCO_RR::
-* SCTP_RR::
-
-Using Netperf to Measure Aggregate Performance
-
-* Running Concurrent Netperf Tests::
-* Using --enable-burst::
-
-Using Netperf to Measure Bidirectional Transfer
-
-* Bidirectional Transfer with Concurrent Tests::
-* Bidirectional Transfer with TCP_RR::
-
-Other Netperf Tests
-
-* CPU rate calibration::
-
File: netperf.info, Node: Introduction, Next: Installing Netperf, Prev: Top, Up: Top
@@ -413,31 +341,43 @@
The `--enable-demo=yes' configure option will cause code to be
included to report interim results during a test run. The rate at
which interim results are reported can then be controlled via the
-global `-D' option. Here is an example of -enable-demo mode output:
+global `-D' option. Here is an example of `-D' output:
- src/netperf -D 1.35 -H lag -f M
- TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to lag.hpl.hp.com (15.4.89.214) port 0 AF_INET : demo
- Interim result: 9.66 MBytes/s over 1.67 seconds
- Interim result: 9.64 MBytes/s over 1.35 seconds
- Interim result: 9.58 MBytes/s over 1.36 seconds
- Interim result: 9.51 MBytes/s over 1.36 seconds
- Interim result: 9.71 MBytes/s over 1.35 seconds
- Interim result: 9.66 MBytes/s over 1.36 seconds
- Interim result: 9.61 MBytes/s over 1.36 seconds
+ $ src/netperf -D 1.35 -H tardy.hpl.hp.com -f M
+ MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to tardy.hpl.hp.com (15.9.116.144) port 0 AF_INET : demo
+ Interim result: 5.41 MBytes/s over 1.35 seconds ending at 1308789765.848
+ Interim result: 11.07 MBytes/s over 1.36 seconds ending at 1308789767.206
+ Interim result: 16.00 MBytes/s over 1.36 seconds ending at 1308789768.566
+ Interim result: 20.66 MBytes/s over 1.36 seconds ending at 1308789769.922
+ Interim result: 22.74 MBytes/s over 1.36 seconds ending at 1308789771.285
+ Interim result: 23.07 MBytes/s over 1.36 seconds ending at 1308789772.647
+ Interim result: 23.77 MBytes/s over 1.37 seconds ending at 1308789774.016
Recv Send Send
Socket Socket Message Elapsed
Size Size Size Time Throughput
bytes bytes bytes secs. MBytes/sec
- 32768 16384 16384 10.00 9.61
+ 87380 16384 16384 10.06 17.81
Notice how the units of the interim result track that requested by
the `-f' option. Also notice that sometimes the interval will be
longer than the value specified in the `-D' option. This is normal and
-stems from how demo mode is implemented without relying on interval
-timers, but by calculating how many units of work must be performed to
-take at least the desired interval.
+stems from how demo mode is implemented not by relying on interval
+timers or frequent calls to get the current time, but by calculating
+how many units of work must be performed to take at least the desired
+interval.
+ Those familiar with this option in earlier versions of netperf will
+note the addition of the "ending at" text. This is the time as
+reported by a `gettimeofday()' call (or its emulation) with a `NULL'
+timezone pointer. This addition is intended to make it easier to
+insert interim results into an rrdtool
+(http://oss.oetiker.ch/rrdtool/doc/rrdtool.en.html) Round-Robin
+Database (RRD). A likely bug-riddled example of doing so can be found
+in `doc/examples/netperf_interim_to_rrd.sh'. The time is reported out
+to milliseconds rather than microseconds because that is the most
+rrdtool understands as of the time of this writing.
+
As of this writing, a `make install' will not actually update the
files `/etc/services' and/or `/etc/inetd.conf' or their
platform-specific equivalents. It remains necessary to perform that
@@ -488,14 +428,16 @@
Netperf is designed around a basic client-server model. There are two
executables - netperf and netserver. Generally you will only execute
the netperf program, with the netserver program being invoked by the
-remote system's inetd or equivalent. When you execute netperf, the
-first that that will happen is the establishment of a control
-connection to the remote system. This connection will be used to pass
-test configuration information and results to and from the remote
-system. Regardless of the type of test to be run, the control
-connection will be a TCP connection using BSD sockets. The control
-connection can use either IPv4 or IPv6.
+remote system's inetd or having been previously started as its own
+standalone daemon.
+ When you execute netperf it will establish a "control connection" to
+the remote system. This connection will be used to pass test
+configuration information and results to and from the remote system.
+Regardless of the type of test to be run, the control connection will
+be a TCP connection using BSD sockets. The control connection can use
+either IPv4 or IPv6.
+
Once the control connection is up and the configuration information
has been passed, a separate "data" connection will be opened for the
measurement itself using the API's and protocols appropriate for the
@@ -522,9 +464,10 @@
CPU utilization is an important, and alas all-too infrequently reported
component of networking performance. Unfortunately, it can be one of
-the most difficult metrics to measure accurately as many systems offer
-mechanisms that are at best il-suited to measuring CPU utilization in
-high interrupt rate (eg networking) situations.
+the most difficult metrics to measure accurately and portably. Netperf
+will do its level best to report accurate CPU utilization figures, but
+some combinations of processor, OS and configuration may make that
+difficult.
CPU utilization in netperf is reported as a value between 0 and 100%
regardless of the number of CPUs involved. In addition to CPU
@@ -537,7 +480,7 @@
Service demand can be particularly useful when trying to gauge the
effect of a performance change. It is essentially a measure of
-efficiency, with smaller values being more efficient.
+efficiency, with smaller values being more efficient and thus "better."
Netperf is coded to be able to use one of several, generally
platform-specific CPU utilization measurement mechanisms. Single
@@ -571,7 +514,7 @@
`P'
An HP-UX-specific CPU utilization mechanism whereby the kernel
keeps-track of time (in the form of CPU cycles) spent in the kernel
- idle loop (HP-UX 10.0 to 11.23 inclusive), or where the kernel
+ idle loop (HP-UX 10.0 to 11.31 inclusive), or where the kernel
keeps track of time spent in idle, user, kernel and interrupt
processing (HP-UX 11.23 and later). The former requires
calibration, the latter does not. Values in either case are
@@ -580,14 +523,14 @@
`src/netcpu_pstat.c' and `src/netcpu_pstatnew.c' respectively.
`K'
- A Solaris-specific CPU utilization mechanism where by the kernel
+ A Solaris-specific CPU utilization mechanism whereby the kernel
keeps track of ticks (eg HZ) spent in the idle loop. This method
is statistical and is known to be inaccurate when the interrupt
rate is above epsilon as time spent processing interrupts is not
subtracted from idle. The value is retrieved via a kstat() call -
hence the use of the letter `K'. Since this mechanism uses units
of ticks (HZ) the calibration value should invariably match HZ.
- (Eg 100) The code for this mechanism is implemented in
+ (Eg 100) The code for this mechanism is implemented in
`src/netcpu_kstat.c'.
`M'
@@ -619,9 +562,9 @@
what appears to be a form of micro-state accounting and requires no
calibration. On laptops, or other systems which may dynamically
alter the CPU frequency to minimize power consumtion, it has been
- suggested that this mechanism may become slightly confsed, in
- which case using BIOS settings to disable the power saving would
- be indicated.
+ suggested that this mechanism may become slightly confused, in
+ which case using BIOS/uEFI settings to disable the power saving
+ would be indicated.
`S'
This mechanism uses `/proc/stat' on Linux to retrieve time (ticks)
@@ -639,7 +582,7 @@
using the times() and getrusage() calls. These calls are actually
rather poorly suited to the task of measuring CPU overhead for
networking as they tend to be process-specific and much
- network-related processing can happen outside the context of a
+ network-related processing can happen outside the context of a
process, in places where it is not a given it will be charged to
the correct, or even a process. They are mentioned here as a
warning to anyone seeing those mechanisms used in other networking
@@ -680,7 +623,32 @@
with other mechanisms. However, platform tools such as top, vmstat or
mpstat are often based on the same mechanisms used by netperf.
+* Menu:
+
+* CPU Utilization in a Virtual Guest::
+
+File: netperf.info, Node: CPU Utilization in a Virtual Guest, Prev: CPU Utilization, Up: CPU Utilization
+
+3.1.1 CPU Utilization in a Virtual Guest
+----------------------------------------
+
+The CPU utilization mechanisms used by netperf are "inline" in that
+they are run by the same netperf or netserver process as is running the
+test itself. This works just fine for "bare iron" tests but runs into
+a problem when using virtual machines.
+
+ A virtual guest can be thought of as being similar to a process in a
+bare iron system. As such, any CPU utilization mechanisms used in the
+virtual guest are similar to "process-local" mechanisms in a bare iron
+situation. However, just as with bare iron, much networking processing
+happens outside the context of the virtual guest. It takes place in
+the hypervisor, and is not visible to mechanisms running in the
+guest(s). For this reason, one should not really trust CPU utilization
+figures reported by netperf or netserver when running in a virtual
+guest.
+
+
File: netperf.info, Node: Global Command-line Options, Next: Using Netperf to Measure Bulk Data Transfer, Prev: The Design of Netperf, Up: Top
4 Global Command-line Options
@@ -2476,7 +2444,7 @@
specified in the test-specific `-b' option.
-File: netperf.info, Node: Using Netperf to Measure Bidirectional Transfer, Next: Other Netperf Tests, Prev: Using Netperf to Measure Aggregate Performance, Up: Top
+File: netperf.info, Node: Using Netperf to Measure Bidirectional Transfer, Next: The Omni Tests, Prev: Using Netperf to Measure Aggregate Performance, Up: Top
8 Using Netperf to Measure Bidirectional Transfer
*************************************************
@@ -2590,11 +2558,224 @@
verbosity of 2 or more with the global `-v' option.
-File: netperf.info, Node: Other Netperf Tests, Next: Address Resolution, Prev: Using Netperf to Measure Bidirectional Transfer, Up: Top
+File: netperf.info, Node: The Omni Tests, Next: Other Netperf Tests, Prev: Using Netperf to Measure Bidirectional Transfer, Up: Top
-9 Other Netperf Tests
-*********************
+9 The Omni Tests
+****************
+Beginning with version 2.5.0, netperf begins a migration to the "omni"
+tests or "Two routines to measure them all." The code for the omni
+tests can be found in `src/nettest_omni.c' and the goal is to make it
+easier for netperf to support multiple protocols and report a great
+many additional things about the systems under test. Additionally, a
+flexible output selection mechanism is present which allows the user to
+chose specifically what values she wishes to have reported and in what
+format.
+
+ The omni tests are included by default in version 2.5.0. To disable
+them, one must:
+ ./configure --enable-omni=no ...
+
+ and remake netperf. Remaking netserver is optional because even in
+2.5.0 it has "unmigrated" netserver side routines for the classic (eg
+`src/nettest_bsd.c') tests.
+
+* Menu:
+
+* Native Omni Tests::
+* Migrated Tests::
+* Omni Output Selection::
+
+
+File: netperf.info, Node: Native Omni Tests, Next: Migrated Tests, Prev: The Omni Tests, Up: The Omni Tests
+
+9.1 Native Omni Tests
+=====================
+
+One access the omni tests "natively" by using a value of "OMNI" with
+the global `-t' test-selection option. This will then cause netperf to
+use the code in `src/nettest_omni.c' and in particular the
+test-specific options parser for the omni tests. The test-specific
+options for the omni tests are a superset of those for "classic" tests.
+The options added by the omni tests are:
+
+`-c'
+ This explicitly declares that the test is to include connection
+ establishment and tear-down as in either a TCP_CRR or TCP_CC test.
+
+`-d <direction>'
+ This option sets the direction of the test relative to the netperf
+ process. As of version 2.5.0 one can use:
+
+ `send, xmit or 2'
+ Any of which will cause netperf to send to the netserver.
+
+ `recv, receive or 4'
+ Any of which will cause netserver to send to netperf.
+
+ `rr or 6'
+ Either of which will cause a request/response test.
+
+`-k <output selector>'
+ This option sets the style of output to "keyval" where each line of
+ output has the form:
+ key=value
+ For example:
+ $ netperf -t omni -- -d rr -k "THROUGHPUT,THROUGHPUT_UNITS"
+ OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ THROUGHPUT=59092.65
+ THROUGHPUT_UNITS=Trans/s
+
+ Using the `-k' option will override any previous, test-specific
+ `-o' or `-O' option.
+
+`-o <output selector>'
+ This option sets the style of output to "CSV" where there will be
+ one line of comma-separated values, preceeded by one line of column
+ names unless the global `-P' option is used with a value of 0:
+ $ netperf -t omni -- -d rr -o "THROUGHPUT,THROUGHPUT_UNITS"
+ OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ Throughput,Throughput Units
+ 60999.07,Trans/s
+
+ Using the `-o' option will override any previous, test-specific
+ `-k' or `-O' option.
+
+`-O <output selector>'
+ This option sets the style of output to "human readable" which will
+ look quite similar to classic netperf output:
+ $ netperf -t omni -- -d rr -O "THROUGHPUT,THROUGHPUT_UNITS"
+ OMNI TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ Throughput Throughput
+ Units
+
+
+ 60492.57 Trans/s
+
+ Using the `-O' option will override any previous, test-specific
+ `-k' or `-o' option.
+
+`-T <protocol>'
+ This option is used to explicitly set the protocol used for the
+ test.
+
+ The default is implicit based on other settings.
+
+
+File: netperf.info, Node: Migrated Tests, Next: Omni Output Selection, Prev: Native Omni Tests, Up: The Omni Tests
+
+9.2 Migrated Tests
+==================
+
+As of version 2.5.0 several tests have been migrated to use the omni
+code in `src/nettest_omni.c' for the core of their testing. A migrated
+test retains all its previous output code and so should still "look and
+feel" just like a pre-2.5.0 test with one exception - the first line of
+the test banners will include the word "MIGRATED" at the beginning as
+in:
+
+ $ ../src/netperf
+ MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ Recv Send Send
+ Socket Socket Message Elapsed
+ Size Size Size Time Throughput
+ bytes bytes bytes secs. 10^6bits/sec
+
+ 87380 16384 16384 10.00 27175.27
+
+ The tests migrated in version 2.5.0 are:
+ * TCP_STREAM
+
+ * TCP_MAERTS
+
+ * TCP_RR
+
+ * TCP_CRR
+
+ * UDP_STREAM
+
+ * UDP_RR
+
+ It is expected that future releases will have additional tests
+migrated to use the "omni" functionality.
+
+ If one uses "omni-specific" test-specific options in conjunction
+with a migrated test, instead of using the classic output code, the new
+omni output code will be used. For example if one uses the `-k'
+test-specific option with a value of "MIN_LATENCY,MAX_LATENCY" with a
+migrated TCP_RR test one will see:
+
+ $ ../src/netperf -t tcp_rr -- -k THROUGHPUT,THROUGHPUT_UNITS
+ MIGRATED TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ THROUGHPUT=60074.74
+ THROUGHPUT_UNITS=Trans/s
+ rather than:
+ $ ../src/netperf -t tcp_rr
+ MIGRATED TCP REQUEST/RESPONSE TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to localhost.localdomain (127.0.0.1) port 0 AF_INET : demo
+ Local /Remote
+ Socket Size Request Resp. Elapsed Trans.
+ Send Recv Size Size Time Rate
+ bytes Bytes bytes bytes secs. per sec
+
+ 16384 87380 1 1 10.00 59421.52
+ 16384 87380
+
+
+File: netperf.info, Node: Omni Output Selection, Prev: Migrated Tests, Up: The Omni Tests
+
+9.3 Omni Output Selection
+=========================
+
+The omni test-specific `-k', `-o' and `-O' options take an optional
+`output selector' by which the user can configure what values are
+reported. The output selector can take several forms:
+
+``filename''
+ The output selections will be read from the named file. Within the
+ file there can be up to four lines of comma-separated output
+ selectors. This controls how many multi-line blocks of output are
+ emitted when the `-O' option is used. This output, while not
+ identical to "classic" netperf output, is inspired by it.
+ Multiple lines have no effect for `-k' and `-o' options. Putting
+ output selections in a file can be useful when the list of
+ selections is long.
+
+`comma and/or semi-colon-separated list'
+ The output selections will be parsed from a comma and/or
+ semi-colon-separated list of output selectors. When the list is
+ given to a `-O' option a semi-colon specifies a new output block
+ should be started. Semi-colons have the same meaning as commas
+ when used with the `-k' or `-o' options. Depending on the command
+ interpreter being used, the semi-colon may have to be escaped
+ somehow to keep it from being interpreted by the command
+ interpreter. This can often be done by enclosing the entire list
+ in quotes.
+
+`all'
+ If the keyword all is specified it means that all known output
+ values should be displayed at the end of the test. This can be a
+ great deal of output. As of version 2.5.0 there are 157 different
+ output selectors.
+
+`?'
+ If a "?" is given as the output selection, the list of all known
+ output selectors will be displayed and no test actually run. When
+ passed to the `-O' option they will be listed one per line.
+ Otherwise they will be listed as a comma-separated list. It may
+ be necessary to protect the "?" from the command interpreter by
+ escaping it or enclosing it in quotes.
+
+`no selector'
+ If nothing is given to the `-k', `-o' or `-O' option then the code
+ selects a default set of output selectors inspired by classic
+ netperf output.
+
+
+File: netperf.info, Node: Other Netperf Tests, Next: Address Resolution, Prev: The Omni Tests, Up: Top
+
+10 Other Netperf Tests
+**********************
+
Apart from the typical performance tests, netperf contains some tests
which can be used to streamline measurements and reporting. These
include CPU rate calibration (present) and host identification (future
@@ -2607,8 +2788,8 @@
File: netperf.info, Node: CPU rate calibration, Prev: Other Netperf Tests, Up: Other Netperf Tests
-9.1 CPU rate calibration
-========================
+10.1 CPU rate calibration
+=========================
Some of the CPU utilization measurement mechanisms of netperf work by
comparing the rate at which some counter increments when the system is
@@ -2653,7 +2834,7 @@
File: netperf.info, Node: Address Resolution, Next: Enhancing Netperf, Prev: Other Netperf Tests, Up: Top
-10 Address Resolution
+11 Address Resolution
*********************
Netperf versions 2.4.0 and later have merged IPv4 and IPv6 tests so the
@@ -2692,7 +2873,7 @@
File: netperf.info, Node: Enhancing Netperf, Next: Netperf4, Prev: Address Resolution, Up: Top
-11 Enhancing Netperf
+12 Enhancing Netperf
********************
Netperf is constantly evolving. If you find you want to make
@@ -2710,6 +2891,10 @@
4. Compile and test
+ However, with the addition of the "omni" tests in version 2.5.0 it
+is preferred that one attempt to make the necessary changes to
+`src/nettest_omni.c' rather than adding new source files.
+
If you wish to submit your changes for possible inclusion into the
mainline sources, please try to base your changes on the latest
available sources. (*Note Getting Netperf Bits::.) and then send email
@@ -2723,7 +2908,7 @@
File: netperf.info, Node: Netperf4, Next: Concept Index, Prev: Enhancing Netperf, Up: Top
-12 Netperf4
+13 Netperf4
***********
Netperf4 is the shorthand name given to version 4.X.X of netperf. This
@@ -2824,8 +3009,10 @@
* -b, Global: Global Options. (line 22)
* -C, Global: Global Options. (line 42)
* -c, Global: Global Options. (line 33)
+* -c, Test-specific: Native Omni Tests. (line 13)
* -D, Global: Global Options. (line 56)
* -d, Global: Global Options. (line 47)
+* -d, Test-specific: Native Omni Tests. (line 17)
* -F, Global: Global Options. (line 76)
* -f, Global: Global Options. (line 67)
* -H, Global: Global Options. (line 94)
@@ -2839,6 +3026,7 @@
* -i, Global: Global Options. (line 178)
* -I, Global: Global Options. (line 129)
* -j, Global: Global Options. (line 199)
+* -k, Test-specific: Native Omni Tests. (line 30)
* -L, Global: Global Options. (line 241)
* -l, Global: Global Options. (line 221)
* -L, Test-specific <1>: Options Common to TCP UDP and SCTP _RR tests.
@@ -2853,6 +3041,8 @@
* -n, Global: Global Options. (line 253)
* -O, Global: Global Options. (line 316)
* -o, Global: Global Options. (line 307)
+* -O, Test-specific: Native Omni Tests. (line 55)
+* -o, Test-specific: Native Omni Tests. (line 43)
* -P, Global: Global Options. (line 340)
* -p, Global: Global Options. (line 320)
* -P, Test-specific <1>: Options Common to TCP UDP and SCTP _RR tests.
@@ -2870,6 +3060,7 @@
* -s, Test-specific: Options common to TCP UDP and SCTP tests.
(line 64)
* -t, Global: Global Options. (line 349)
+* -T, Test-specific: Native Omni Tests. (line 69)
* -V, Global: Global Options. (line 403)
* -v, Global: Global Options. (line 381)
* -W, Global: Global Options. (line 415)
@@ -2879,57 +3070,62 @@
Tag Table:
Node: Top439
-Node: Introduction2700
-Node: Conventions5161
-Node: Installing Netperf6924
-Node: Getting Netperf Bits8478
-Node: Installing Netperf Bits10296
-Node: Verifying Installation17626
-Node: The Design of Netperf18330
-Node: CPU Utilization19912
-Node: Global Command-line Options28525
-Node: Command-line Options Syntax29064
-Node: Global Options30446
-Node: Using Netperf to Measure Bulk Data Transfer51150
-Node: Issues in Bulk Transfer51815
-Node: Options common to TCP UDP and SCTP tests55966
-Node: TCP_STREAM62268
-Node: TCP_MAERTS66036
-Node: TCP_SENDFILE67273
-Node: UDP_STREAM69589
-Node: XTI_TCP_STREAM73025
-Node: XTI_UDP_STREAM73670
-Node: SCTP_STREAM74315
-Node: DLCO_STREAM75015
-Node: DLCL_STREAM76988
-Node: STREAM_STREAM77862
-Node: DG_STREAM78720
-Node: Using Netperf to Measure Request/Response79401
-Node: Issues in Request/Response81322
-Node: Options Common to TCP UDP and SCTP _RR tests83328
-Node: TCP_RR88307
-Node: TCP_CC90651
-Node: TCP_CRR92848
-Node: UDP_RR93894
-Node: XTI_TCP_RR95915
-Node: XTI_TCP_CC96498
-Node: XTI_TCP_CRR96664
-Node: XTI_UDP_RR96832
-Node: DLCL_RR97409
-Node: DLCO_RR97562
-Node: SCTP_RR97714
-Node: Using Netperf to Measure Aggregate Performance97850
-Node: Running Concurrent Netperf Tests98685
-Node: Using --enable-burst102577
-Node: Using Netperf to Measure Bidirectional Transfer108763
-Node: Bidirectional Transfer with Concurrent Tests109836
-Node: Bidirectional Transfer with TCP_RR111702
-Node: Other Netperf Tests114236
-Node: CPU rate calibration114682
-Node: Address Resolution117023
-Node: Enhancing Netperf118999
-Node: Netperf4120236
-Node: Concept Index121146
-Node: Option Index123472
+Node: Introduction1475
+Node: Conventions3936
+Node: Installing Netperf5699
+Node: Getting Netperf Bits7253
+Node: Installing Netperf Bits9071
+Node: Verifying Installation17265
+Node: The Design of Netperf17969
+Node: CPU Utilization19565
+Node: CPU Utilization in a Virtual Guest28280
+Node: Global Command-line Options29291
+Node: Command-line Options Syntax29830
+Node: Global Options31212
+Node: Using Netperf to Measure Bulk Data Transfer51916
+Node: Issues in Bulk Transfer52581
+Node: Options common to TCP UDP and SCTP tests56732
+Node: TCP_STREAM63034
+Node: TCP_MAERTS66802
+Node: TCP_SENDFILE68039
+Node: UDP_STREAM70355
+Node: XTI_TCP_STREAM73791
+Node: XTI_UDP_STREAM74436
+Node: SCTP_STREAM75081
+Node: DLCO_STREAM75781
+Node: DLCL_STREAM77754
+Node: STREAM_STREAM78628
+Node: DG_STREAM79486
+Node: Using Netperf to Measure Request/Response80167
+Node: Issues in Request/Response82088
+Node: Options Common to TCP UDP and SCTP _RR tests84094
+Node: TCP_RR89073
+Node: TCP_CC91417
+Node: TCP_CRR93614
+Node: UDP_RR94660
+Node: XTI_TCP_RR96681
+Node: XTI_TCP_CC97264
+Node: XTI_TCP_CRR97430
+Node: XTI_UDP_RR97598
+Node: DLCL_RR98175
+Node: DLCO_RR98328
+Node: SCTP_RR98480
+Node: Using Netperf to Measure Aggregate Performance98616
+Node: Running Concurrent Netperf Tests99451
+Node: Using --enable-burst103343
+Node: Using Netperf to Measure Bidirectional Transfer109529
+Node: Bidirectional Transfer with Concurrent Tests110597
+Node: Bidirectional Transfer with TCP_RR112463
+Node: The Omni Tests114997
+Node: Native Omni Tests116044
+Node: Migrated Tests118895
+Node: Omni Output Selection121024
+Node: Other Netperf Tests123287
+Node: CPU rate calibration123702
+Node: Address Resolution126045
+Node: Enhancing Netperf128021
+Node: Netperf4129450
+Node: Concept Index130360
+Node: Option Index132686
End Tag Table
Modified: trunk/doc/netperf.pdf
===================================================================
(Binary files differ)
Modified: trunk/doc/netperf.texi
===================================================================
(Binary files differ)
Modified: trunk/doc/netperf.xml
===================================================================
(Binary files differ)
More information about the netperf-dev
mailing list