ACE/performance-tests/SCTP/README.SCTP_PERF_TEST

   1 Release 1.0 - January 2003
   2
   3 ***********************************
   4 *    Performance Test Overview    *
   5 ***********************************
   6
   7 This directory contains performance tests for measuring round-trip
   8 latency statistics of ACE synchronous messaging using unmarshalled
   9 ACE_CDR::Octet.
  10
  11 In terms of protocol and service type, three different tests are
  12 available:
  13
  14  * TCP over SOCK_STREAM
  15  * SCTP over SOCK_STREAM
  16  * SCTP over SOCK_SEQPACK
  17
  18 All three of these tests share the same architecture, which is
  19 described in the following section.
  20
  21 ***************************
  22 *    Test Architecture    *
  23 ***************************
  24
  25 As mentioned above, the performance tests measure round-trip latency
  26 statistics.  We are talking about the round trip between two service
  27 endpoints, a client and a server.  The client sends the server an
  28 arbitrary message with a specific length---up to 2^16 bytes---and the
  29 server responds with a 2-byte reply.  The client measures and records
  30 the time it takes to complete this exchange.  The whole test is then
  31 repeated through many iterations, and finally the client outputs the
  32 resulting statistics.
  33
  34 In detail,
  35
  36 1.  The server program is started first.  It creates a passive-mode
  37     socket and runs an infinite loop waiting for clients to connect.
  38
  39 2.  The client program is started next.  It may be configured with
  40     numerous parameters, which include:
  41
  42       * the hostname and port where the server's passive-mode socket
  43         is listening,
  44       * the desired message length, which may be any power of two
  45         between 2^0 and 2^16,
  46       * the desired number of iterations (by default 1 million)
  47
  48 3.  The client connects to the server's passive-mode socket.  If all
  49     goes well, the client and server will each obtain a data-mode
  50     socket that serves as a communication endpoint.
  51
  52 4.  The client sends an initial header message containing the intended
  53     number of iterations and the message length (which will be
  54     the same for each iteration).  Armed with this information, the
  55     server spawns a separate thread to handle these iterations.
  56
  57 5.  The client creates an in-memory data structure that serves as a
  58     histogram.  The histogram is configured with a range of possible
  59     round-trip latencies, and this range is divided into a number of
  60     "bins".  The latency measured for each test entry will either
  61     fall into one of these "bins", or it will fall outside the entire
  62     range and will be logged as an outlier.
  63
  64 6.  The client and server repeat the following interaction for each
  65     test iteration.
  66
  67     a.  The client starts a stopwatch.
  68
  69     b.  The client sends the server an arbitrary message of the
  70         established length.
  71
  72     c.  After receiving this entire message from the client, the
  73         server sends the client a 2-byte reply.
  74
  75     d.  After receiving the 2-byte reply from the server, the client
  76         stops the stopwatch.
  77
  78     e.  The round-trip latency, as measureed by the stopwatch, is
  79         logged to the in-memory histogram.
  80
  81 7.  After all these iterations are complete, the client disconnects
  82     from the server.  The client then takes the in-memory histogram
  83     and dumps its text representation to STDOUT.
  84
  85 8.  The client exits.  The server thread dedicated to this client
  86     exits.  The main thread of the server continues to run an infinite
  87     loop waiting for more clients to connect to the passive-mode
  88     socket.
  89
  90 **************************
  91 *    Test Executables    *
  92 **************************
  93
  94 You must use a different pair of client and server executables
  95 depending on whether you desire to use the SOCK_STREAM service or the
  96 SOCK_SEQPACK service.
  97
  98 The SOCK_STREAM client and server are called SOCK_STREAM_clt and
  99 SOCK_STREAM_srv, respectively.  The SOCK_SEQPACK client and server are
 100 called SOCK_SEQPACK_clt and SOCK_SEQPACK_srv, respectively.
 101
 102 Each of these executables uses SCTP as its default protocol.  As an
 103 extra feature, SOCK_STREAM_clt and SOCK_STREAM_srv offer TCP as an
 104 alternate protocol.  The choice between TCP and SCTP is exposed via
 105 the '-t' option.  (Individual instances of SOCK_STREAM_clt and
 106 SOCK_STREAM_srv must use the same protocol in order to connect and
 107 function.)
 108
 109 Any of the four executables will show usage information if you run it
 110 with the '-h' option.  For instance, here is the usage message
 111 produced by SOCK_STREAM_clt:
 112
 113 ./SOCK_STREAM_clt - Measures round trip latency statistics of ACE synchronous
 114                     messaging (SOCK_Stream) using unmarshalled ACE_CDR::Octet.
 115 USAGE: ./SOCK_STREAM_clt [ -<flag> [<val>] | --<name> [<val>] ]...
 116
 117   Flag  Args           Option-Name                 Default
 118    -c   int            test-iterations             1000000
 119    -n   none           test-enable-nagle           NO NAGLING
 120    -t   str (sctp|tcp) test-transport-protocol     sctp
 121
 122    -m   dbl            histogram-min-bin           0
 123    -M   dbl            histogram-max-bin           10000
 124    -x   int            histogram-num-outliers      100
 125    -b   int            histogram-bin-count         1000
 126
 127    -C   int            client-port                 assigned by kernel
 128    -i   str            client-connect-addr         INADDR_ANY
 129
 130    -p   int            server-port                 45453
 131    -H   str            server-host                 localhost
 132
 133    -s   int (0-16)     payload-size-power-of-2     <MUST SET VALUE>
 134
 135    -h   none           help
 136
 137 For each option, the long "Option-Name" may be prefixed by two dashes
 138 and used on the command line in place of the shorter "Flag".  Hence
 139
 140    ./SOCK_STREAM_clt -s 5
 141
 142 is equivalent to
 143
 144    ./SOCK_STREAM_clt --payload-size-power-of-2 5
 145
 146 The options shown above for SOCK_STREAM_clt (and the similar options
 147 available for SOCK_SEQPACK_clt) are discussed in the next section.
 148
 149 *****************************
 150 *    Client-Side Options    *
 151 *****************************
 152
 153 The following options are available for both SOCK_STREAM_clt and
 154 SOCK_SEQPACK_clt.
 155
 156     test-iterations  [ -c int ]
 157
 158         the number of times to repeat the round-trip-latency test
 159         loop.  The default is 1000000.
 160
 161     test-enable-nagle  [ -n ]
 162
 163         Enable Nagle's algorithm (which is disabled by default).
 164
 165     histogram-min-bin  [ -m double ]
 166
 167         the lower boundary on the range of the histogram.
 168         The default is 0.  The unit of measurement is the millisecond.
 169
 170     histogram-max-bin  [ -M double ]
 171
 172         the upper boundary on the range of the histogram.
 173         The default is 10000.  The unit of measurement is the
 174         millisecond.
 175
 176     histogram-num-outliers  [ -x int ]
 177
 178         the maximum number of outliers to maintain in the histogram.
 179         The default is 100.
 180
 181     histogram-bin-count  [ -b int ]
 182
 183         the number of histogram bins.  The default is 1000.  The width
 184         of each bin will be
 185
 186           (histogram-max-bin - histogram-min-bin) / histogram-bin-count
 187
 188     client-port          [ -C int ]
 189     client-connect-addr  [ -i string ]
 190
 191         the port and network address where the client's data-mode
 192         socket is to be bound.  By default, the port number is
 193         assigned by the kernel, and the socket is bound to all network
 194         interfaces.
 195
 196     server-port  [ -p int ]
 197     server-host  [ -H string ]
 198
 199         the port and hostname where the server's passive-mode socket
 200         is bound.  The default port is 45453 and the default host is
 201         localhost.
 202
 203     payload-size-power-of-2  [ -s int ]
 204
 205         an integer X.  The size of the payload will be 2^X bytes.
 206
 207     help  [ -h ]
 208
 209         Show usage message.
 210
 211 The following option is available only for SOCK_STREAM_clt:
 212
 213     test-transport-protocol  [ -t (sctp|tcp) ]
 214
 215         the protocol for the test.  The default is sctp.
 216
 217 In contrast, SOCK_SEQPACK_clt always uses SCTP as its protocol.
 218
 219 *****************************
 220 *    Server-Side Options    *
 221 *****************************
 222
 223 The following options are available for both SOCK_STREAM_srv and
 224 SOCK_SEQPACK_srv:
 225
 226     test-enable-nagle  [ -n ]
 227
 228         Enable Nagle's algorithm (which is disabled by default).
 229
 230     server-port  [ -p int ]
 231
 232         the port where the server's passive-mode socket will be
 233         bound.  The default is 45453.
 234
 235     help  [ -h ]
 236
 237         Show usage message.
 238
 239 The following option is available for both SOCK_STREAM_srv and
 240 SOCK_SEQPACK_srv, but the latter offers additional functionality:
 241
 242     server-accept-addr  [ -a w.x.y.z ]              (for SOCK_STREAM_srv)
 243                         [ -a w.x.y.z,a.b.c.d,... ]  (for SOCK_SEQPACK_srv)
 244
 245         the network address (or addresses) to which the server's
 246         passive-mode socket will be bound.
 247
 248         The default value of INADDR_ANY should be sufficient for
 249         machines that have only one network interface.
 250
 251         If your machine has two interfaces, and you wish to bind the
 252         socket only to one of these, then you may explicitly specify
 253         the desired interface with an expression such as
 254         "-a 192.168.221.104" or "-a 192.168.1.43".
 255
 256         If your machine has three or more interfaces, and you wish to
 257         bind the socket only to a subset of two or more, AND you are
 258         using SOCK_SEQPACK_srv, THEN you may explicitly specify the
 259         desired interface with an expression such as
 260         "-a 192.168.221.104,192.168.1.43".  The argument here is a
 261         comma-delimited list of dotted-decimal IPv4 addresses with no
 262         whitespace interspersed.  This level of control is not
 263         possible with SOCK_STREAM_srv.
 264
 265 The following option is available only for SOCK_STREAM_srv:
 266
 267     test-transport-protocol  [ -t (sctp|tcp) ]
 268
 269         the protocol for the test.  The default is sctp.
 270
 271 In contrast, SOCK_SEQPACK_srv always uses SCTP as its protocol.
 272
 273 ***************************
 274 *    Test Walk-Through    *
 275 ***************************
 276
 277 This section shows a walk-through of a typical scenario using
 278 SOCK_STREAM_clt and SOCK_STREAM_srv to run an SCTP performance test.
 279
 280 You can run the equivalent TCP performance test by adding "-t tcp" to
 281 the command line of both programs.  Alternately, you can run a
 282 SOCK_SEQPACK-based SCTP performance test by substituting
 283 SOCK_SEQPACK_clt and SOCK_SEQPACK_srv for SOCK_STREAM_clt and
 284 SOCK_STREAM_srv, respectively.
 285
 286 In this scenario, both client and server run on the same machine.  We
 287 use a message size of 2^7 bytes and a relatively small number of
 288 iterations, 1000, in order to make the test go quickly.  The server's
 289 passive-mode socket binds to the default port, 45453, which is also
 290 the default port expected by the client.  We invoke no other special
 291 or unusual options.
 292
 293 For clarity, we envision starting the client and server in two
 294 separate shells.
 295
 296 The steps of the walk-through are as follows:
 297
 298 1.  Start the server.
 299
 300     $ ./SOCK_STREAM_srv
 301     (12761|1024) Accepting connections on port 45453
 302                  on interface INADDR_ANY using IPPROTO_SCTP
 303     (12761|1024) starting server at port 45453
 304     (12761|1024) select timed out
 305     (12761|1024) select timed out
 306     (12761|1024) select timed out
 307     (12761|1024) select timed out
 308     ...
 309
 310     The server will continue to print, periodically, the message
 311     "select timed out" as it waits for clients to connect.
 312
 313 2.  Start the client.
 314
 315     $ ./SOCK_STREAM_clt -s 7 -c 1000
 316
 317 3.  Observing the debugging output from the server, you should see
 318     evidence that the client has connected.
 319
 320     (12761|1024) select timed out
 321     (12761|1024) select timed out
 322     (12761|1024) select timed out
 323     (12761|1024) spawning server
 324     (12761|1024) client utica-b connected from 32768
 325     (12761|1024) Test for 1100 iterations
 326     (12761|1024) select timed out
 327     (12761|1024) select timed out
 328
 329     Note that the server expects 1100 iterations, even though we
 330     configured the client for only 1000 iterations.  The reason for
 331     this discrepencany is that the client always runs 100 primer
 332     iterations before the requested test iterations.
 333
 334 4.  When the 1100 iterations are complete, observing the output from
 335     the client, you should see the histogram:
 336
 337
 338                                 Histogram ACE Unmarshalled Msg Synchronous Latency Test
 339                                         (Message Size 128, Message Type octet)
 340     version: 1.1
 341     minimum: 41
 342     maximum: 60182
 343     mean: 106.858
 344     variance: 3.62659e+06
 345     num_points: 1000
 346     num_bins: 1000 0 10000
 347
 348               Low     -          High     Count  Fraction  Cumulative
 349              below    -         0.000  :      0    0.000    0.000
 350                0.000  -        10.000  :      0    0.000    0.000
 351               10.000  -        20.000  :      0    0.000    0.000
 352               20.000  -        30.000  :      0    0.000    0.000
 353               30.000  -        40.000  :      0    0.000    0.000
 354               40.000  -        50.000  :    988    0.988    0.988
 355               50.000  -        60.000  :      5    0.005    0.993
 356               60.000  -        70.000  :      2    0.002    0.995
 357               70.000  -        80.000  :      0    0.000    0.995
 358               80.000  -        90.000  :      1    0.001    0.996
 359               90.000  -       100.000  :      0    0.000    0.996
 360              100.000  -       110.000  :      0    0.000    0.996
 361     ...
 362             9960.000  -      9970.000  :      0    0.000    0.999
 363             9970.000  -      9980.000  :      0    0.000    0.999
 364             9980.000  -      9990.000  :      0    0.000    0.999
 365             9990.000  -     10000.000  :      0    0.000    0.999
 366            10000.000  -       above    :      1    0.001    1.000
 367
 368     outliers:
 369            60182.000
 370
 371 ******************************************
 372 *    Running a Complete Test Spectrum    *
 373 ******************************************
 374
 375 People who are interested in round-trip latency often want to see a
 376 "spectrum" of statistics for a range of payload sizes.  This directory
 377 includes a script, run_spectrum.pl, that automates running
 378 SOCK_STREAM_clt or SOCK_SEQPACK_clt multiple times in order to
 379 generate a spectrum.  (The appropriate server program must be started
 380 manually.)
 381
 382 The run_spectrum.pl script offers embedded documentation.  To see the
 383 full documentation, please run
 384
 385    ./run_spectrum.pl --manual
 386
 387 ************************
 388 *    Sample Results    *
 389 ************************
 390
 391 The file sample-spectrum.png plots the spectrum data for a test run at
 392 LM ATL facilities on the following systems:  two Linux 2.4.18, 1600 MHz
 393 Pentium 4 machines on an isolated 100Mbps Ethernet network.
 394
 395 The test conditions include several critical parameters that were set
 396 as follows:
 397
 398    sctp_rto_initial = 20
 399    sctp_rto_min     = 20
 400    sctp_rto_max     = 20
 401
 402 Testing has shown that these parameters affect maximum round-trip
 403 latency.