EMA C++ Performace Tools Guide : 4 Consumer Performance Tool : 4.4 EmaCppConsPerf Configuration Options
 
4.4 EmaCppConsPerf Configuration Options
EmaCppConsPerf uses EmaConfig.xml configuration file to setup an EMA consumer and set of command line options to configure specific behavior of performance tool.
EmaConfig.xml must have Consumer section in the Consumer group and appropriate Channel section in Channel group for correct configuration of the EMA consumer. For details on how to setup Consumer and Channel sections, refer to the Enterprise Message API Configuration Guide. For examples of configuration, refer to Section 4.5.1.
EmaCppConsPerf uses the command line option -consumerName to specify name of Consumer section.
The following table describes available configuration options.
 
Table 2: EmaCppConsPerf Configuration Options  
COMMAND-LINE OPTION
DEFAULT
DESCRIPTION
-apiThreads
-1
Specifies the CPU core(s) to which the internal EMA API thread(s) will be bound to dispatch received messages. The parameter is used when the application configures EMA to work in API dispatch mode (see
-useUserDispatch). EmaCppConsPerf does not bind the internal EMA API thread(s) to specific CPU core(s) by default. For details on the internal EMA API thread, refer to the Enterprise Message API Developers Guide, 2.4 Product Architecture.
Specifies the CPU physical mapping in format P:X C:Y T:Z, logical core ID (number), or no binding (-1).
Specifies the physical mapping which binds the thread to the specified physical processor, core, and thread (P:X C:Y T:Z). This syntax specifies a physical CPU to bind to. P refers to processor, C refers to core, and T refers to thread. If T is not specified (or T:#), the thread will be bound to all threads on the specified processor. If C is not specified (or C:#), the thread will be bound to all cores and threads on that processor. 
Specifying only one number causes a logical core ID to be bound instead of a physical one. 
-1 means no bind.
For example, when specified as "1,3", the internal EMA API threads will be bound to logical CPU cores 1 and 3. 
The number of threads set by the parameter -threads should be matched. 
For details on rsslBindThread, refer to the Transport API C++ Edition Developers Guide.
-commonItemCount
0
If multiple consumer threads are created (see -threads), each thread normally requests a unique set of items on its connection. This option specifies the number of common items to be requested by all connections.
-consumerName
Perf_Consumer_
Specifies the name of consumer in XML configuration file (EmaConfig.xml).Configures the name of the Consumer component in the configuration file (EmaConfig.xml) that will be used to configure the connection.
-delaySteadyStateCalc
0
Configures the time duration (in milliseconds), the consumer needs to wait to calculate the latency after receiving the last expected image.
-genericMsgLatencyRate
0
Controls the number of generic messages sent per second that contain latency information. This must be less than or equal to the total generic message rate (see -genericMsgRate).
-genericMsgRate
0
Controls the number of generic messages sent per second. This cannot be less than the tick rate, unless it is zero (see -tickRate).
-itemCount
100000
Sets the total number of items requested by the consumer.
-itemFile
350k.xml
Configures the name of the item list file.
-latencyFile
None
Sets the name of the log file in which EmaCppConsPerf logs the latency retrieved from individual latency updates, generic messages, and posts. If a name is not specified, logging is disabled.
-mainThread
-1
Specifies the CPU core to bind the main application thread that controls working threads, collects and prints statistics. By default, EmaCppConsPerf does not bind the main thread to specific CPU core.
Specifies the CPU physical mapping in format P:X C:Y T:Z, logical core ID (number), or no binding (-1).
Specifies the physical mapping which binds the thread to the specified physical processor, core, and thread (P:X C:Y T:Z). This syntax specifies a physical CPU to bind to. P refers to processor, C refers to core, and T refers to thread. If T is not specified (or T:#), the thread will be bound to all threads on the specified processor. If C is not specified (or C:#), the thread will be bound to all cores and threads on that processor.
Specifying only one number causes a logical core ID to be bound instead of a physical one. -1 means no bind.
For example, when specified "3", the main thread will be bound to logical CPU core 3.
For details on rsslBindThread, refer to the Transport API C++ Edition Developers Guide.
-msgFile
MsgData.xml
Configures the name of the file used by the consumer to determine the makeup of message payloads. For more details on input file information, refer to Section 8.1.
-noDisplayStats
(no argument)
Turns off printing statistics to the screen.
-postingLatencyRate
0
Controls the number of posts sent per second that contain latency information. This must be less than or equal to the total post message rate (see -postingRate).
-postingRate
0
Configures the consumer for posting. Sets the number of posting messages the consumer sends, per second. This cannot be less than the tick rate, unless it is zero (see -tickRate).
-requestRate
35000
Sets the number of item requests sent (per second).
-serviceName
DIRECT_FEED
Configures the name of the service used by the consumer to request items. The consumer begins requesting items whenever this service is found and appears ready.
-snapshot
(no argument)
Opens all items as snapshots, even if not specified in the item list file, and exits upon receiving all the solicited images. This is different from setting
-steadyStateTime to 0 in that the requests are specifically made without the "STREAMING" RequestMsg flag.
-spTLSv1.2
(no argument)
Specifies that TLSv1.2 can be used for an OpenSSL-based encrypted connection.
-spTLSv1.3
(no argument)
Specifies that TLSv1.3 can be used for an OpenSSL-based encrypted connection.
-statsFile
ConsStats
Configures the base name that the consumer uses when writing its test statistics.
-steadyStateTime
300
Configures how long (in seconds) the consumer continues to run the test after receiving the last expected image.
steadyStateTime has a second function: after beginning the test, if the consumer does not receive all expected images within this segment of time, the consumer times out. In this case, it exits and indicates that it did not reach steady state.
-summaryFile
ConsSummary.out
Configures the name of the file to which the consumer writes its test summary.
-threads
None
The value of "-threads" serves two purposes: It defines the number of parallel threads/connections to be created AND where to bind each thread. For example, if an application wants to horizontally scale and open two connections, there should be two values for -threads: 0,1 OR P:0 C:0 T:0, P:0 C:0 T:1 OR -1, -1. The number of values specified indicates the number of threads to start (comma separated). The thread binding may be formatted or specified as follows: physical binding (P:X C:Y T:Z) OR logical binding (X) or -1 (no binding). 
Physical binding: specify physical CPU to bind to: P refers to processor, C refers to core, and T refers to thread. If T is not specified (or T:#), the thread will be bound to all threads on the specified processor. If C is not specified (or C:#), the thread will be bound to all cores and threads on that processor. 
Logical Binding: For example, "1,3" creates two threads to establish connections with the provider, respectively bound to logical CPU cores 1 and 3. 
In conjunction with -threads, one may specify -apiThreads,
-workerThreads.
For details on rsslBindThread, refer to the Transport API C++ Edition Developers Guide.
-tickRate
1000
Sets the number of 'ticks' per second (the number of times per second the main loop of the consumer occurs). Adjusting the tick rate changes the size of request/post bursts; a higher tick rate results in smaller individual bursts, creating smoother traffic.
-uname
None
Sets the user name for the login request. When unspecified, the system login name is used.
-useServiceId
0
Configures the consumer for adding the field "serviceId" in the Request message. For details on Request message, refer to Enterprise Message API LSEG Domain Model Usage Guide.
-useUserDispatch
0
Configures how EmaCppConsPerf and the Enterprise Message API dispatch received messages. When you select 0 (API dispatch model) then EmaCppConsPerf configures the Enterprise Message API to create an additional internal thread to dispatch received messages. When you select 1 (user dispatch model) the Enterprise Message API does not run a second thread and the EmaCppConsPerf is responsible for dispatching all received messages. By default, EmaCppConsPerf uses the API dispatch model.
For details on how an Enterprise Message API application dispatches received messages, refer to the Enterprise Message API Developers Guide.
-websocket
None
Configures the consumer for using websocket connection with specified protocol: "rssl.json.v2" or "rssl.rwf".
-workerThreads
None
Specifies the CPU core(s) to which the Reactor worker thread(s) will be bound. EmaCppConsPerf does not bind the Reactor worker thread(s) to specific CPU core(s) by default. For details on Value Added Components, refer to the Transport API Value Added Components Developers Guide.
Specifies the CPU physical mapping in format P:X C:Y T:Z, logical core ID (number), or no binding (-1).
Specifies the physical mapping which binds the thread to the specified physical processor, core, and thread (P:X C:Y T:Z). This syntax specifies a physical CPU to bind to. P refers to processor, C refers to core, and T refers to thread. If T is not specified (or T:#), the thread will be bound to all threads on the specified processor. If C is not specified (or C:#), the thread will be bound to all cores and threads on that processor.
Specifying only one number causes a logical core ID to be bound instead of a physical one.
-1 means no bind.
For example, “1,3” specifies two Reactor worker threads, respectively bound to logical CPU cores 1 and 3.
The number of threads set by the parameter -threads should be matched.
For details on rsslBindThread, refer to the Transport API C++ Edition Developers Guide.
-writeStatsInterval
5
Configures the frequency (in seconds) at which statistics are printed to the screen and statistics file.