0001 EXBENCHCL(8)
0002 ============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 exbenchcl - Enduro/X benchmark tool
0009
0010
0011 SYNOPSIS
0012 --------
0013 exbenchcl ['OPTIONS']
0014
0015
0016 DESCRIPTION
0017 -----------
0018 *exbenchcl* is Enduro/X benchmark tool. Tool is used for benchmarking standard
0019 *tpcall(3)* request/reply messages. Also tool supports persistent queue *tpenqueue(3)*
0020 and *tpdequeue(3)* benchmarking. Tools supports multi-threading and multi-processing.
0021 Test duration can be limited either by specified runtime in seconds or by optional
0022 number of messages processed by each processing unit (thread or processes).
0023
0024 Currently supported data buffer format is *UBF*. Data loaded to UBF is loaded
0025 in following way (may be combined):
0026
0027 . Data loaded from command line argument *-b* which is in format of *tpjsontoubf(3)*
0028
0029 . Random data generated and set in specified UBF CARRAY field in CLI options.
0030
0031
0032 The benchmark result is appended to benchmark output file, in following format:
0033
0034 --------------------------------------------------------------------------------
0035
0036 "Configuration" "MsgSize" "CallsPerSec"
0037 "<config_name>" <msg_size_in_bytes> <calls_per_second>
0038 "<config_name>" <msg_size_in_bytes> <calls_per_second>
0039 ...
0040
0041 --------------------------------------------------------------------------------
0042
0043 When performing benchmark to persistent queue, the default mode is to enqueue
0044 and dequeue message.
0045
0046 *WARNING*: Binary is experimental and may be changed in future releases (including
0047 but not limited with replaced CLI flags, etc).
0048
0049 ENVIRONMENT
0050 -----------
0051 [*NDRX_BENCH_FILE*]::
0052 Benchmark output text file name. If not set, default name *test.out* is written
0053 in current directory.
0054
0055 [*NDRX_BENCH_CONFIGNAME*]::
0056 Configuration name used in benchmark file. If not specified, default value *test*
0057 is used.
0058
0059 OPTIONS
0060 -------
0061 [*-n* 'NR_OF_THREADS']::
0062 Number of worker threads. In fork mode (*-F*), this configures the number of worker
0063 forked processes. Default is *1*.
0064
0065 [*-s* 'CALL_SERVICE_NAME']::
0066 This configures the target service name. For queue testing mode (*-Q* specified),
0067 this identifies the target persistent queue name. In case if using multiple
0068 service (*-N* specified) names or queues, then actual service / queue name used
0069 by thread is constructed 'CALL_SERVICE_NAME' appended with NNN, formatted as
0070 current thread number by modulus of the total number of services (*-N* value).
0071 Total service name length must not be longer than 30 symbols (name is truncated
0072 to 30 chars). Default is *EXBENCH*.
0073
0074 [*-t* 'RUN_TIME_SECONDS']::
0075 Number of seconds for test to run. The default is *60*.
0076
0077 [*-d* 'OUTPUT_DIRECTOR']::
0078 Optional flag for changing output directory where object file is generated. If
0079 parameter is not set, current directory is used.
0080
0081 [*-b* 'SAMPLE_DATA_STRING']::
0082 UBF sample data in form of *tpjsontoubf(3)*. 1024 bytes are allocated for target
0083 buffer.
0084
0085 [*-S* 'RANDOM_DATA_SIZE']::
0086 This specified random field size (field specified by *-f*) in bytes. The default
0087 value is *1024*.
0088
0089 [*-p* 'PRIO']::
0090 Absolute call priority, if specified then before *tpcall(3)* or *tpenqueue(3)*
0091 the *tpsprio(3)* is executed by worker thread or process.
0092
0093 [*-P*]::
0094 Plot the results in benchmark output file. If this parameter is not specified,
0095 results are not written to benchmark output file.
0096
0097 [*-f* 'UBF_FIELD_NAME']::
0098 This parameter specifies CARRAY typed field name were random blob data of size specified
0099 by *-S* shall be loaded.
0100
0101 [*-F*]::
0102 Use fork mode, instead of threads.
0103
0104 [*-N* 'NUMBER_OF_SERVICES']::
0105 This parameter enables multi service/queue mode and in the same time specifies
0106 total number of services or queues used in test. The default value is *0*, meaning
0107 that service name specified in *-s* is used without appending with the service/queue
0108 number.
0109
0110 [*-Q* 'QUEUE_SPACE_NAME']::
0111 This parameter if set enables persistent queue tests and at the same time it
0112 specifies the queue space name used for *tpenqueue(3)* and *tpdequeue(3)* calls.
0113
0114 [*-A*]::
0115 Enable testing of *tmqueue(8)* automatic forwarding queue. During the test
0116 specified run-time, messages are enqueued only. Once time (or message count
0117 *-R*) have been exceeded, the worker thread/process will perform periodic
0118 peek to message queue, to ensure that count is 0 (thus all messages have been
0119 forwarded). By default if *-A* or *-E* flags are not specified, then persistent
0120 queue benchmark is performed as pair of *tpenqueue(3)* and *tpdequeue(3)* operations.
0121
0122 [*-E*]::
0123 Persist messages only (for *-Q* mode). Thus only *tpenqueue(3)* is executed.
0124
0125 [*-R* 'NUMBER_OF_REQUESTS']::
0126 If set, then this parameter limits the benchmarking additionally to number
0127 of messages processed by worker thread. Benchmark will terminate in either
0128 time is reached or number of requests reached, which ever comes first. Total
0129 number of requests is made by test is multiplied by worker thread/process count.
0130
0131 [*-T* 'TRANSACTION_TIMEOUT']::
0132 If flag is set and value 'TRANSACTION_TIMEOUT' is greater than 0, worker threads
0133 will perform calls in global transaction. This means that *exbenchcl* must
0134 have proper transaction environment. If this flag is not set, the XATMI calls
0135 are not run in transaction mode.
0136
0137 [*-I*]::
0138 Used for process to wait for *tpnotify(3)* call from server back to benchmark
0139 client. In this mode, benchmark tool sets the XATMI client id in *EX_CLTID* UBF
0140 field. When *exbenchsv* receives the request and if it sees that *EX_CLTID* is set,
0141 it performs the tpnotify() call with the request buffer and only after
0142 that performs tpreturn().
0143
0144 [*-e*]::
0145 Perform *tppost(3)* instead of *tpcall(3)*. If parameter is set, event name
0146 is set in *-s* parameter.
0147
0148 [*-h*]::
0149 Print usage.
0150
0151 EXIT STATUS
0152 -----------
0153 *0*::
0154 Success
0155
0156 *1*::
0157 Failure
0158
0159
0160 CONFIGURATION EXAMPLE
0161 ---------------------
0162
0163 Responder service in *ndrxconfig.xml(5)*, single service name mode *-N* (not set or 0).
0164
0165 --------------------------------------------------------------------------------
0166
0167 <server name="exbenchsv">
0168 <srvid>1800</srvid>
0169 <min>15</min>
0170 <max>15</max>
0171 <sysopt>-e /tmp/EXBENCH</sysopt>
0172 </server>
0173
0174 --------------------------------------------------------------------------------
0175
0176 Responder service in *ndrxconfig.xml(5)*, multi-service mode, 5 services:
0177
0178 --------------------------------------------------------------------------------
0179
0180 <server name="exbenchsv">
0181 <srvid>1800</srvid>
0182 <min>15</min>
0183 <max>15</max>
0184 <sysopt>-e /tmp/EXBENCH</sysopt>
0185 <appopt>-N5</appopt>
0186 </server>
0187
0188 --------------------------------------------------------------------------------
0189
0190 EXAMPLE
0191 -------
0192
0193 Benchmark of UBF buffer at 1024 bytes with 5 threads:
0194
0195 --------------------------------------------------------------------------------
0196
0197 $ exbenchcl -n5 -P -t20 -b "{}" -f EX_DATA -S1024
0198
0199 --------------------------------------------------------------------------------
0200
0201 Benchmark of 10 threads, to 5 service names
0202
0203 --------------------------------------------------------------------------------
0204
0205 $ exbenchcl -n10 -P -t20 -b "{}" -f EX_DATA -S1024 -N5
0206
0207 --------------------------------------------------------------------------------
0208
0209 Persistent queue benchmark to queue space named *SAMPLESPACE*. Queue name
0210 used is *TESTQ1*:
0211
0212 --------------------------------------------------------------------------------
0213
0214 $ exbenchcl -n10 -P -t20 -b "{}" -f EX_DATA -S1024 -QSAMPLESPACE -sTESTQ1
0215
0216 --------------------------------------------------------------------------------
0217
0218
0219 BUGS
0220 ----
0221 Report bugs to support@mavimax.com
0222
0223
0224 SEE ALSO
0225 --------
0226 *exbenchsv(8)* *ndrxconfig.xml(5)*
0227
0228
0229 COPYING
0230 -------
0231 (C) Mavimax, Ltd
0232
