Skip to content

Commit 7e267fd

Browse files
ChrisJ60ChrisJ60
committed
Updates to documentation.
1 parent a5e1e3e commit 7e267fd

File tree

3 files changed

+249
-231
lines changed

3 files changed

+249
-231
lines changed

‎LICENSE.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# nweventwatcher
1+
# nwtest
22

33
You may not use the identified files except in compliance with the Universal Permissive License, Version 1.0 (the "License.")
44

‎README.md

+12-230
Original file line numberDiff line numberDiff line change
@@ -1,236 +1,18 @@
11
## nwtest
22

3-
This program implements a network response time and throughput test.
3+
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

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

227-
To give this some context, with the default message size of 1024 bytes the IPv4
228-
packet size will be 1076 bytes and the IPv6 packet size will be 1096 bytes.
229-
Both will therefore fit into a single Ethernet/WiFi frame. The associated
230-
Ethernet frame will be 1114 bytes for IPv4 and 1134 bytes for IPv6. With a
231-
1 Gb Ethernet network the maximum theoretical throughput will therefore be
232-
112,208 frames/s for IPv4 and 110,229 frames/s for IPv6. This translates to
233-
a theoretical maximum application data rate of 109.5 Mbyte/s for IPv4 and
234-
107.6 Mbyte/s for IPv6.
14+
## Contact
15+
16+
You may contact the author at [email protected]
23517

23618

0 commit comments

Comments
 (0)