HPX - High Performance ParalleX

PrevUpHomeNext
Consuming Performance Counter Data from the Command Line

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:

Table 26. HPX Command Line Options Related to Performance Counters

Command line option

Description

--hpx:print-counter

print the specified performance counter either repeatedly or before shutting down the system (see option --hpx:print-counter-interval)

--hpx:print-counter-interval

print the performance counter(s) specified with --hpx:print-counter repeatedly after the time interval (specified in milliseconds) (default: 0, which means print once at shutdown)

--hpx:print-counter-destination

print the performance counter(s) specified with --hpx:print-counter to the given file (default: console)

--hpx:list-counters

list the names of all registered performance counters

--hpx:list-counter-infos

list the description of all registered performance counters

--hpx:print-counter-format

print the performance counter(s) specified with --hpx:print-counter, possible formats in csv format with header or without any header (see option --hpx:no-csv-header) values: 'csv' (prints counter values in CSV format with full names as header) 'csv-short' (prints counter values in CSV format with shortnames provided with --hpx:print-counter as --hpx:print-counter shortname,full-countername)

--hpx:no-csv-header

print the performance counter(s) specified with --hpx:print-counter and csv or csv-short format specified with --hpx:print-counter-format without header


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] 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{locality#0/total}/count/bind

which yields for instance:

hello world from OS-thread 0 on locality 0
/threads{locality#0/total}/count/cumulative,1,0.212527,[s],33
/agas{locality#0/total}/count/bind,1,0.212790,[s],11

The first line is the normal output generated by hello_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 6 fields, the counter name, the sequence number of the counter invocation, the time stamp at which this information has been sampled, the unit of measure for the time stamp, the actual counter value, and an optional unit of measure for the 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{locality#0/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{locality#0/total}/count/bind,1,0.002542[s],9
threads{locality#0/total}/count/cumulative,2,0.023002[s],41
agas{locality#0/total}/count/bind,2,0.023557[s],10
threads{locality#0/total}/count/cumulative,3,0.037514[s],46
agas{locality#0/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

The command --hpx:print-counter-format takes values csv and csv-short to generate CSV formatted counter values with header

With format as csv:

hello_world \
    --hpx:threads=2 \
    --hpx:print-counter-format csv \
    --hpx:print-counter /threads{locality#*/total}/count/cumulative \
    --hpx:print-counter /threads{locality#*/total}/count/cumulative-phases

will print the values of performance counters in CSV format with full countername as header

hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
/threads{locality#*/total}/count/cumulative,/threads{locality#*/total}/count/cumulative-phases
39,93

With format csv-short:

hello_world \
    --hpx:threads 2 \
    --hpx:print-counter-format csv-short \
    --hpx:print-counter cumulative,/threads{locality#*/total}/count/cumulative \
    --hpx:print-counter phases,/threads{locality#*/total}/count/cumulative-phases

will print the values of performance counters in CSV format with short countername as header

hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
cumulative,phases
39,93

With format csv and csv-short when used with --hpx:print-counter-interval:

hello_world \
    --hpx:threads 2 \
    --hpx:print-counter-format csv-short \
    --hpx:print-counter cumulative,/threads{locality#*/total}/count/cumulative \
    --hpx:print-counter phases,/threads{locality#*/total}/count/cumulative-phases \
    --hpx:print-counter-interval 5

will print the header only once repeating the performance counter value(s) repeatidly

cum,phases
25,42
hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
44,95

The command --hpx:no-csv-header to be used with --hpx:print-counter-format to print performance counter values in CSV format without any header

hello_world \
--hpx:threads 2 \
--hpx:print-counter-format csv-short \
--hpx:print-counter cumulative,/threads{locality#*/total}/count/cumulative \
--hpx:print-counter phases,/threads{locality#*/total}/count/cumulative-phases \
--hpx:no-csv-header

will print

hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
37,91

PrevUpHomeNext