All Performance Counter instances have a name uniquely identifying this instance. This name can be used to access the counter, retrieve all related meta data, and to query the counter data (as described in the section Consuming Performance Counters). Counter names are strings with a predefined structure. The general form of a countername is:
could be either another (full) counter name or a string formatted as:
Each separate part of a countername (e.g.
start with a letter (
'Z') or an underscore character (
'_'), optionally followed by letters, digits
'-'), or underscore characters.
Whitespace is not allowed inside a counter name. The characters
'@' have a special meaning
and are used to delimit the different parts of the counter name.
instanceindex are integers.
If an index is not specified HPX will assume a default
An instance for a well formed (and meaningful) simple counter name would be:
This counter returns the current cumulative number of executed (retired)
HPX-threads for the locality
The counter type of this counter is
/threads/count/cumulative and the full instance name
for readability). This counter type does not require an
parameters to be specified.
In this case, the
'0') designates the locality
for which the counter instance is created. The counter will return the
number of HPX-threads retired on that particular locality.
Another example for a well formed (aggregate) counter name is:
This counter takes the simple counter from the first example, samples its
and returns the average of the value samples whenever it is queried. The
counter type of this counter is
/statistics/average and the instance name is the
full name of the counter for which the values have to be averaged. In this
'500') specify the sampling interval
for the averaging to take place (in milliseconds).
Every Performance Counter belongs to a specific Performance Counter type
which classifies the counters into groups of common semantics. The type
of a counter is identified by the
of the name.
At application start, HPX will register all available counter types on each of the localities. These counter types are held in a special Performance Counter registration database which can be later used to retrieve the meta data related to a counter type and to create counter instances based on a given counter instance name.
different counter instances of the same counter type. The formatting of
on the counter type. There are two types of counters: simple counters which
usually generate the counter values based on direct measurements, and aggregate
counters which take another counter and transform its values before generating
their own counter values. An example for a simple counter is given above: counting
retired HPX-threads. An aggreagate counter is shown
as an example above
as well: calculating the average of the underlying counter values sampled
at constant time intervals.
While simple counters use instance names formatted as
most aggregate counters have the full counter name of the embedded counter
as its instance name.
Not all simple counter types require specifying all 4 elements of a full
counter instance name, some of the parts (
are optional for specific counters. Please refer to the documentation of
a particular counter for more information about the formatting requirements
for the name of this counter (see Existing
parameters are used
to pass additional information to a counter at creation time. They are
optional and they fully depend on the concrete counter. Even if a specific
counter type allows additional parameters to be given, those usually are
not required as sensible defaults will be chosen. Please refer to the documentation
of a particular counter for more information about what parameters are
supported, how to specify them, and what default values are assumed (see
Every locality of an application exposes its own set of Performance Counter types and Performance Counter instances. The set of exposed counters is determinded dynamically at application start based on the execution environment of the application. For instance, this set is influenced by the current hardware environment for the locality (such as whether the locality has access to accelerators), and the software environment of the application (such as the number of OS-threads used to execute HPX-threads).
It is possible to use wildcard characters when specifying performance counter names. Performance counter names can contain 2 types of wildcard characters:
Wildcard character have a meaning which is very close to usual file name wildcard matching rules implemented by common shells (like bash).
Table 23. Wildcard characters in the performance counter type
This wildchard character matches any number (zero or more) of arbitrary characters.
This wildchard character matches any single arbitrary character.
This wildchard character matches any single character from the list of specified within the square brackets.
Table 24. Wildcard characters in the performance counter instance name
This wildchard character matches any locality or any thread,
depending on whether it is used for