Skip to content

Commit aa4b9e3

Browse files
ChrisJ60ChrisJ60
committed
Fixed calculation of average throughput. Improved online help.
1 parent 2382691 commit aa4b9e3

8 files changed

+474
-424
lines changed

‎NwtestHelp.txt

+274
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
2+
Version 2.0
3+
4+
This program implements a network response time and throughput test.
5+
6+
The program can be run as either a client or a server. The client opens one
7+
or more connections to a server and exchanges messages of a given size with
8+
the server for a given period of time. At the end of the test period, various
9+
performance metrics are displayed.
10+
11+
The test can run in two modes. In synchronous (request/response) mode, each
12+
connection has a single thread in both the client and the server. Once the
13+
connection is established the client sends a message to the server and waits
14+
for a response. As soon as the server receives a message it sends it straight
15+
back to the client. This sequence is repeated until the test ends.
16+
17+
In asynchronous (streaming) mode, each connection has two threads in both the
18+
client and the server. Once the connection is established the client sends a
19+
continuous stream of messages to the server and the server simultaneously
20+
sends a continuous stream of messages to the client.
21+
22+
The size of the messages exchanged, the duration of the test measurement phase,
23+
the amount of load ramp-up and ramp-down time and the number of connections
24+
(and hence threads) are all configurable.
25+
26+
The defaults for the various configurable parameters have been carefully chosen
27+
such that using the defaults will generally give a meaningful result. The main
28+
parameters that you might vary in normal usage are the message size and the
29+
number of connections.
30+
31+
32+
Usage:
33+
34+
nwtest h[elp] { h[elp] | u[sage] | g[eneral] | c[lient] |
35+
s[erver] | m[etrics] | f[ull] }
36+
37+
nwtest s[erver] <port> [ -4 | -6 ] [ -h[ost] <h> ] [ -m[sgsz] <m> ]
38+
[ -c[onn] <c> ] [ -l[og] <logpath> ]
39+
40+
nwtest c[lient] <host> <port> [ -s[rc] <srcaddr>] [ -4 | -6 ] [ -a[sync] ]
41+
[ -c[onn] <c> ] [ -d[ur] <d> ] [ -r[amp] <r> ]
42+
[ -m[sgsz] <m> ] [ -l[og] <logpath> ]
43+
[ -bsz <bsz> | [ -sbsz <sbsz> ] [ -rbsz <rbsz> ] ]
44+
[ -n[odelay] ] [ -b[rief] | -v[erbose] ]
45+
46+
47+
nwtest h[elp] { u[sage] | g[eneral] | c[lient] | s[erver] | m[etrics] | f[ull] }
48+
49+
Display help on the specified topic.
50+
51+
52+
nwtest s[erver] <port> [ -4 | -6 ] [ -h[ost] <h> ] [ -m[sgsz] <m> ]
53+
[ -c[onn] <c> ] [ -l[og] <logpath> ]
54+
55+
Run as a server on local port <port>. If a specific host is specified (<h>)
56+
then bind to the address(es) for that host, otherwise bind to INADDR[6]_ANY.
57+
The host can be specified as a hostname or an IP address (IPv4 or IPv6);
58+
the address specified must be an address for an interface on the local system.
59+
If a hostname is specified then you can use the '-4' or '-6' options to limit
60+
communication to IPv4 or IPv6.
61+
62+
The maximum message size, in bytes, that the server will accept is specified
63+
by <m> where 28 <= <m> <= 1,048,576. Connections requesting a message size
64+
larger than this will be rejected. The default is 1,048,576. This size
65+
represents the size of the user data; it excludes network protocol overheads
66+
(ethernet, IPv4/6 etc.). The size may be specified using a suffix of 'k' to
67+
repesent KB (1,024 bytes) or 'm' to represent MB (1,048,576 bytes).
68+
69+
The maximum number of concurrent connections that the server will allow is set
70+
using <c> where 2 <= <c> <= 128. Connections that exceed this number will
71+
be rejected. The default is 32.
72+
73+
Normally all output goes to stdout/stderr, but if '-log' is specified then
74+
after initial argument parsing any subsequent messages will be written only
75+
to <logpath> with microsecond resolution timestamps. A <logpath> of '-'
76+
equates to 'stdout' and '--' equates to 'stderr'.
77+
78+
79+
nwtest c[lient] <host> <port> [ -s[rc] <srcaddr>] [ -4 | -6 ] [ -a[sync] ]
80+
[ -c[onn] <c> ] [ -d[ur] <d> ] [ -r[amp] <r> ]
81+
[ -m[sgsz] <m> ] [ -l[og] <logpath> ]
82+
[ -bsz <bsz> | [ -sbsz <sbsz> ] [ -rbsz <rbsz> ] ]
83+
[ -n[odelay] ] [ -b[rief] | -v[erbose] ]
84+
85+
Run as a client connecting to a server at host <host> and port <port>. The
86+
host can be specified as either a host name or an IP address (IPv4 or IPv6).
87+
If a hostname is specified then you can use the '-4' or '-6' options to limit
88+
communication to IPv4 or IPv6.
89+
90+
Normally the OS will determine the local source IP address (interface) to use
91+
for the outgoing connection, but this can be overridden by specifying an
92+
explicit local address using the '-src' option. This value must be an IP
93+
address, not a hostname, and it must correspond to the address of an
94+
interface on the local system. If <host> has been specified using an IP
95+
address then the address type (IPv4 or IPv6) for <srcaddr> must be the same
96+
as that of <host>. Furthermore, if the allowed connection type has been
97+
restricted by way of '-4' or '-6' then the value of <srcaddr> must be of
98+
the selected type.
99+
100+
By default the test is performed in request/response (synchronous) mode but
101+
if '-async' is specified the test is performed in streaming mode.
102+
103+
The measurement part of the test will run for <d> seconds with a ramp-up/down
104+
of <r> seconds. 10 <= <d> <= 300 with a default of 30 and 0 <= <r> <= 30
105+
with a default of 10.
106+
107+
The message size used for the test is specified by <m> where 28 <= <m> <=
108+
1,048,576 with a default of 1,024. This size represents the size of the user
109+
data; it excludes network protocol overheads (ethernet, IPv4/6 etc.). The
110+
size may be specified using a suffix of 'k' to repesent KB (1,024 bytes) or
111+
'm' to represent MB (1,048,576 bytes).
112+
113+
The number of concurrent connections used is specified by <c> where 1 <= <c>
114+
<= 64 with a default of 1.
115+
116+
Normally all output goes to stdout/stderr, but if '-log' is specified then
117+
after initial argument parsing any subsequent messages will be written only
118+
to <logpath> with microsecond resolution timestamps. A <logpath> of '-'
119+
equates to 'stdout' and '--' equates to 'stderr'.
120+
121+
Normally the OS will allocate the sizes for the socket send and receive
122+
buffers, and these sizes will be reported in the connection messages. If
123+
you want to specify different values for the socket send and receive buffer
124+
sizes then you can do so using '-bsz' (sets size for both send and receive
125+
buffers), '-sbsz' (sets size for the send buffer) and '-rbsz' (sets size
126+
for receive buffer). These values are specified in bytes and each must be
127+
between 8,192 and 8,388,608. Also, the total of the sizes must be <= 8,388,608.
128+
Explicitly specified values will be sent to, and used by, the server. The
129+
size may be specified using a suffix of 'k' to repesent KB (1,024 bytes) or
130+
'm' to represent MB (1,048,576 bytes).
131+
132+
If '-nodelay' is specified then the TCP_NODELAY option is enabled on all
133+
sockets used for data transfer in both the client and the server.
134+
135+
Normally only aggregate performance metrics are displayed, but if '-verbose'
136+
is specified then per connection metrics are also displayed. If '-brief' is
137+
specified then just key metrics are displayed on a single line.
138+
139+
140+
For each connection successfully established, the client and server will
141+
report the TCP MSS (maxseg) value and the size of the socket send and
142+
receive buffers (sndbsz anb rcvbsz).
143+
144+
The metrics measured and reported by this program for each test mode are
145+
as follows; all references to 'data' and 'throughput' refer to application
146+
data excluding network overheads.
147+
148+
All modes
149+
---------
150+
151+
Elapsed time - The wall clock elapsed time for the measurement part
152+
of the test (excludes ramp up/down time).
153+
154+
User CPU time - The amount of user CPU time consumed during the
155+
elapsed time.
156+
157+
System CPU time - The amount of system CPU time consumed during the
158+
elapsed time.
159+
160+
Total CPU time - User time plus system time.
161+
162+
Process CPU usage - The average CPU usage for the nwtest process during
163+
the elapsed time, expressed as a percentage of one
164+
CPU core.
165+
166+
System CPU usage - The average CPU usage for the nwtest process during
167+
the elapsed time, expressed as a percentage of total
168+
available system CPU resources.
169+
170+
Sync (request/response) mode
171+
----------------------------
172+
173+
Total messages - The total number of data messages sent during the
174+
measurement period. The number of received messages
175+
is the same.
176+
177+
Total data - The total number of bytes sent during the measurement
178+
period. The number of received bytes is the same.
179+
180+
Avg measure time - The average measurement time across all threads (µs).
181+
182+
Start variance - The maximum difference between the start times of all
183+
the threads (µs). Only displayed if connections > 1.
184+
185+
Run variance - The maximum difference between the measurement times of
186+
all the threads (µs). Only displayed if connections > 1.
187+
188+
Throughput - The send throughput, aggregated across all connections,
189+
during the measurement period (bytes/second).
190+
191+
Minimum R/T - The lowest round trip time across all connections during
192+
the measurement period (µs).
193+
194+
Average R/T - The average round trip time across all connections during
195+
the measurement period (µs).
196+
197+
Maximum R/T - The highest round trip time across all connections during
198+
the measurement period (µs).
199+
200+
In brief mode the output consists of a single line as follows:
201+
202+
info: results S,<nconn>,<throughput>,<minrt>,<avgrt>,<maxrt>,<proccpu>,<syscpu>
203+
204+
Async (streaming) mode
205+
----------------------
206+
207+
Total msg sent - The total number of messages sent during the measurement
208+
period.
209+
210+
Total msg rcvd - The total number of messages received during the
211+
measurement period.
212+
213+
Total data sent - The total number of bytes sent during the measurement
214+
period.
215+
216+
Total data rcvd - The total number of bytes received during the measurement
217+
period.
218+
219+
Avg measure time - The average measurement time across all threads (µs).
220+
221+
Start variance - The maximum difference between the start times of all
222+
the threads (µs).
223+
224+
Run variance - The maximum difference between the measurement times of
225+
all the threads (µs).
226+
227+
Send throughput - The send throughput, aggregated across all connections,
228+
during the measurement period (bytes/second).
229+
230+
Recv throughput - The receive throughput, aggregated across all connections,
231+
during the measurement period (bytes/second).
232+
233+
Average throughput - The average of the send and receive throughputs.
234+
235+
In brief mode the output consists of a single line as follows:
236+
237+
info: results A,<nconn>,<sendthroughput>,<recvthroughput>,<proccpu>,<syscpu>
238+
239+
Network overheads
240+
-----------------
241+
242+
The message size that you specify defines the size of the 'application data'
243+
in each message sent or received. The actual amount of data for each message
244+
will be larger than this due to various network and protocol related overheads.
245+
246+
For IPv4, there is at least 28 bytes of overhead per message and in unusual
247+
cases this may be as much as 36 bytes. In addition the TCPv4 header is another
248+
24 bytes. In most cases, for this program, the IPv4 packet size will be <message
249+
size> + 52 bytes.
250+
251+
For IPv6/TCP, there is at least 72 bytes of overhead per message and in unusual
252+
cases this may be more due to additional header fields (each is 8 bytes). In
253+
most cases, for this program, the IPv6 packet size will be <message size> + 72
254+
bytes.
255+
256+
For Ethernet the standard Maximum Transmission Unit (MTU) is 1500 bytes. Each
257+
IP packet will be sent as a sequence of one or more Ethernet frames. Each frame
258+
has some overhead; normally this is 38 bytes but if 802.1q VLANs are being used
259+
it will be 42 bytes.
260+
261+
For WiFi the standard Maximum Transmission Unit (MTU) is 1500 bytes. Each IP
262+
packet will be sent as a sequence of one or more WiFi frames. Each frame has
263+
some overhead; normally this is 36 bytes but it may be as much as 44 bytes.
264+
265+
To give this some context, with the default test message size of 1024 bytes the
266+
IPv4 packet size will be 1076 bytes and the IPv6 packet size will be 1096 bytes.
267+
Both will therefore fit into a single Ethernet/WiFi frame. The associated
268+
Ethernet frame will be 1114 bytes for IPv4 and 1134 bytes for IPv6.
269+
270+
With a 1 Gbit/s Ethernet network, the maximum theoretical throughput will be
271+
112,208 frames/s for IPv4 and 110,229 frames/s for IPv6. This translates to
272+
a theoretical maximum application data rate of 109.5 Mbyte/s for IPv4 and
273+
107.6 Mbyte/s for IPv6.
274+

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
A macOS & Linux utility for performing network performance tests. The tool can be used to measure both throughput and latency for TCP/IP connections and can operate in either synchronous (request/response) or asynchronous (streaming) modes.
44

55
## Documentation
6-
Please see the [User Guide](./UserGuide.md).
6+
Please see the file [NwtestHelp.txt](./NwtestHelp.txt).
77

88
## License
99

0 commit comments

Comments
 (0)