HPX provides a set of predefined command line options for every application which uses hpx::init for its initialization. While there are much more command line options available (see HPX Command Line Options), the set of options related to Performance Counters allow one to list existing counters, query existing counters once at application termination or repeatedly after a constant time interval.

The following table summarizes the available command line options:

While the options --hpx:list-counters and --hpx:list-counter-infos give a short listing of all available counters, the full documentation for those can be found in the section Existing Performance Counters.

A Simple Example

All of the commandline options mentioned above can be for instance tested using the hello_world example.

Listing all available counters (hello_world --hpx:list-counters) yields:

List of available counter instances
(replace '`*`' below with the appropriate sequence number)
-------------------------------------------------------------------------
/agas/count/allocate
/agas/count/bind
/agas/count/bind_gid
/agas/count/bind_name
...
/threads{locality#*/allocator#*}/count/objects
/threads{locality#*/total}/count/stack-recycles
/threads{locality#*/total}/idle-rate
/threads{locality#*/worker-thread#*}/idle-rate

Providing more information about all available counters (hello_world --hpx:list-counter-infos) yields:

Information about available counter instances
(replace * below with the appropriate sequence number)
------------------------------------------------------------------------------
fullname: /agas/count/allocate
helptext: returns the number of invocations of the AGAS service 'allocate'
type:     counter_raw
version:  1.0.0
------------------------------------------------------------------------------

------------------------------------------------------------------------------
fullname: /agas/count/bind
helptext: returns the number of invocations of the AGAS service 'bind'
type:     counter_raw
version:  1.0.0
------------------------------------------------------------------------------

------------------------------------------------------------------------------
fullname: /agas/count/bind_gid
helptext: returns the number of invocations of the AGAS service 'bind_gid'
type:     counter_raw
version:  1.0.0
------------------------------------------------------------------------------

...

This command will not only list the counter names but also a short description of the data exposed by this counter.

	Note
	The list of available counters may differ depending on the concrete execution environment (hardware or software) of your application.

Requesting the counter data for one or more performance counters can be achieved by invoking hello_world with a list of counter names:

hello_world \
    --hpx:print-counter=/threads{locality#0/total}/count/cumulative \
    --hpx:print-counter=/agas{root/total}/count/bind

which yields for instance:

hello world from OS-thread 0 on locality 0
/threads{locality#0/total}/count/cumulative,1,0.019633[s],36
/agas{root/total}/count/bind,1,0.020323[s],10

The first line is the normal output generated by hell_world and has no relation to the counter data listed. The last two lines contain the counter data as gathered at application shutdown. These lines have 4 fields, the counter name, the sequence number of the counter invocation, the time stamp at which this information has been sampled, and the actual counter value.

Requesting to query the counter data once after a constant time interval with this command line

hello_world \
    --hpx:print-counter=/threads{locality#0/total}/count/cumulative \
    --hpx:print-counter=/agas{root/total}/count/bind \
    --hpx:print-counter-interval=20

yields for instance (leaving off the actual console output of the hello_world example for brevity):

threads{locality#0/total}/count/cumulative,1,0.002409[s],22
agas{root/total}/count/bind,1,0.002542[s],9
threads{locality#0/total}/count/cumulative,2,0.023002[s],41
agas{root/total}/count/bind,2,0.023557[s],10
threads{locality#0/total}/count/cumulative,3,0.037514[s],46
agas{root/total}/count/bind,3,0.038679[s],10

The command --hpx:print-counter-destination=<file> will redirect all counter data gathered to the specified file name, which avoids cluttering the console output of your application.

The command line option --hpx:print-counter supports using a limited set of wildcards for a (very limited) set of use cases. In particular, all occurences of #* as in locality#* and in worker-thread#* will be automatically expanded to the proper set of performance counter names representing the actual environment for the executed program. For instance, if your program is utilizing 4 worker threads for the execution of HPX threads (see command line option --hpx:threads) the following command line

hello_world \
    --hpx:threads=4 \
    --hpx:print-counter=/threads{locality#0/worker-thread#*}/count/cumulative

will print the value of the performance counters monitoring each of the worker threads:

hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
hello world from OS-thread 3 on locality 0
hello world from OS-thread 2 on locality 0
/threads{locality#0/worker-thread#0}/count/cumulative,1,0.0025214[s],27
/threads{locality#0/worker-thread#1}/count/cumulative,1,0.0025453[s],33
/threads{locality#0/worker-thread#2}/count/cumulative,1,0.0025683[s],29
/threads{locality#0/worker-thread#3}/count/cumulative,1,0.0025904[s],33