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 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 16. 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


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{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.


PrevUpHomeNext