hpmstat Command

Purpose

Provides system-wide hardware performance counter information.

Syntax

hpmstat [ -b time_base ] [ -d ] [ -D metrics ] [ -g event_groups ] [ -H ] [ -k ] [ -m metrics_groups ] [ -o file ] [ -r ] [ -s set ] [ -T ] [ -U ] [-u ] [ -x ] [ -@ ALL | WparName ] interval count

hpmstat [-h]

Description

The hpmstat command provides the execution wall clock time, hardware performance counters information, and derived hardware metrics. It can only be used by a user with root privilege.

When specified without command line options, hpmstat counts the default 1 iteration of user, kernel, and hypervisor (for processors supporting hypervisor mode) activity for 1 second for the default set 1 of events. It then writes the raw counter values and derived metrics to standard output. By default, runlatch is disabled so that counts can be performed while executing in idle cycle.

When the -U option is specified, interval is in microseconds, the iteration count is infinity, and derived metrics are not calculated and written to standard output. This option is ignored if the counter multiplexing mode is specified.

When the -T option is specified, output information is preceded by the time stamp (seconds plus microseconds) and timing information is written as time stamps instead of time in seconds.

Event types to be monitored and the associated hardware performance counters are specified using either the set -s option or by specifying an event group name or set number in the HPM_EVENT_SETone environment variable. Alternatively, specify counter/event pairs (POWER3 / PowerPC 604 RISC Microprocessor) or an event group name (POWER4 and later) in the libHPM_events input file (takes precedence over HPM_EVENT_SET). Each set can be qualified by a counting mode. An event group number or name can be specified by setting the -g option or specifying a comma-separated list of event groups in the HPM_EVENT_GROUP environment variable. In the same manner, each event group can be qualified by a counting mode.

A comma-separated list of event sets can be specified instead of a set number, in which case the counter multiplexing mode is selected. To select all event sets, set the set number value to 0.

Valid event set numbers run from 1 to an upper limit dependent upon the processor type, which can be listed using the pmlist command.

A comma-separated list of derived metrics can be specified by setting the -D option. Each derived metric can be qualified by a counting mode.

A list of derived metric groups can be specified by setting the -m option or by specifying a comma-separated list of derived metric groups in the HPM_PMD_GROUP environment variable. This allows to select all the derived metrics pertaining to the specified groups. Each metric group can be qualified by a counting mode.

When counting in the multiplexing mode, the results must be normalized to be used. The default base used for the data normalization is the timebase. The -b option allows for the use of the PURR time or the SPURR time (when supported by the processor) for the data normalization. The base for the data normalization can also be defined using the HPM_NORMALIZE environment variable.

When you run the hpmstat command from the global workload partition (WPAR), it is possible to monitor a specific WPAR using the -@ WparName option. You can use the -@ ALL option to monitor all active WPARs in the system and to retrieve per-WPAR data.

Results can be output in XML format using the -x option.

Flags

Item	Description
-@ ALL \| WparName	Selects the target WPAR in which the activity is to be measured. The ALL value means that the hpmstat command measures all active WPARs in the system and reports the activity for each WPAR. This option is only available when you run the hpmstat command from the global WPAR; it is ignored otherwise.
-b time_base	Selects a base for the data normalization. The available bases are as follows: time timebase purr PURR time (when available) spurr SPURR time (when available) The default value is time.
-d	Adds detailed set counts for counter multiplexing mode.
-D metrics	Selects a list of derived metrics to be evaluated. Each derived metric can be qualified by a counting mode as follows: `metric:counting_modes` (See the -m option for available counting modes.)
-g event_groups	Lists a predefined group of events or a comma-separated list of event group names or numbers. When a comma-separated list of groups is used, the counter multiplexing mode is selected. Each event group can be qualified by a counting mode as follows: `event_group:counting_modes` (See the -m option for available counting modes.)
-H	Counts hypervisor activity only.
-h	Displays help message.
-k	Counts system activity only.
-m metrics_groups	Selects a list of derived metric groups to be evaluated. The default derived metric group refers to all derived metrics that do not belong to a specific derived metric group. Each metric group can be qualified by a counting mode as follows: `metric_group_name:counting_modes` The available counting modes are as follows: u user mode k kernel mode h hypervisor mode r runlatch mode n nointerrupt mode
-o file	Output file name.
-r	Enables runlatch and disables counts while executing in idle cycle.
-s set	Lists a predefined set of events or a comma-separated list of sets (`1` to N, or `0` to select all. See the pmlist command.) When a comma-separated list of sets is used, the counter multiplexing mode is selected. Each set can be qualified by a counting mode as follows: `event_set:counting_modes` (See the -m option for available counting modes.)
-T	Writes time stamps instead of time in seconds.
-U	Puts counting time interval in microseconds. This option is ignored if the counter multiplexing mode is specified.
-u	Counts user activity only.
-x	Displays results in VPA XML format.

Parameters

Item	Description
interval	Displays the counting time interval in seconds or microseconds, with a default value of `1`.
count	Shows the number of iterations to count. The default is `1` with an interval in seconds, and infinity when the option -U is specified.

Environment Variables

The following environment variables directly affect the execution of the hpmstat command (there are additional MP_* environment variables that influence the execution of parallel programs).

Item	Description
HPM_EVENT_SET	Selects one of the event sets. The value can be an integer from `1` to `6` on POWER3 systems, `1` to `4` on PowerPC 604 RISC Microprocessor systems, or `1` to a processor-dependent upper limit on POWER4 and later systems. This environment variable is also used to select an event group name on POWER4 and later systems. Each event set can be qualified by a counting mode as follows: `event_set_number:counting_modes` The -g or -s option takes precedence over this variable. The HPM_EVENT_GROUP environment variable takes precedence over this variable.
HPM_EVENT_GROUP	Selects the event groups. A comma-separated list of event groups can be specified. In this case, the counter multiplexing mode is selected. Each event group can be qualified by a counting mode as follows: `event_group_number:counting_modes` The -g or -s option takes precedence over this variable. The HPM_EVENT_GROUP environment variable takes precedence over the HPM_EVENT_SET variable.
HPM_NORMALIZE	Provides the base to be used for the data normalization. The -b option takes precedence over this variable.
HPM_PMD_GROUP	Specifies a comma-separated list of derived metric groups. Each metric group can be qualified by a counting mode. The -m option takes precedence over this variable.
HPM_PMD_METRIC	Specifies a comma-separated list of derived metrics. Each derived metric can be qualified by a counting mode. The -D option takes precedence over this variable.
HPM_DIV_WEIGHT	Provides a weight (an integer greater than `1`) to be used to compute weighted flips on POWER4 systems.
HPM_MX_DURATION	When counting in counter multiplexing mode, this flag specifies the duration of each slice of time. It is expressed in ms, and must lie in the range of 10 ms - 30 s. When this flag is not set, the default value used for the time slice duration is 100 ms.

In addition, the following environment variables, supplied by the user, specify estimations of memory, cache, and TLB miss latencies for the computation of derived metrics. These environment variables do not take precedence over the same estimations eventually provided in the file HPM_flags.env, if present.

HPM_MEM_LATENCY
HPM_L3_LATENCY
HPM_L35_LATENCY
HPM_AVG_L3_LATENCY
HPM_AVG_L2_LATENCY
HPM_L2_LATENCY
HPM_L25_LATENCY
HPM_L275_LATENCY
HPM_L1_LATENCY
HPM_TLB_LATENCY

Exit Status

Item	Description
0	Successful completion.
>0	An error occurred.

Security

Attention RBAC users and Trusted AIX® users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To write information for system, user, and hypervisor activity over a 1 second interval concerning events in set 2 from hardware counters, enter the following command:
```
hpmstat -s 2
```
To write information for the user activity concerning events of group 0 and the system activity concerning events of group 1 for the wpar1 WPAR over a five-second interval, enter the following command:
```
hpmstat -@ wpar1 -g 0:u,1:k 5
```

Location

/usr/bin/perf/pmapi/hpmstat

Standard Input

Not used.

Standard Output

Performance monitoring results are written to stdout, unless the -o file option is specified on the command line.

Standard Error

Used only for diagnostic messages.

Files

The following input files are used if present.

Item Description

Item	Description
libHPM_events	User-supplied event set file. This file does not take precedence over the command lines specified with the -s option. The format for a POWER3/PowerPC 604 RISC Microprocessor counter/event pair is counternumber eventname. For example: `0 PM_LD_MISS_L2HIT 1 PM_TAG_BURSTRD_L2MISS 2 PM_TAG_ST_MISS_L2 3 PM_FPU0_DENORM 4 PM_LSU_IDLE 5 PM_LQ_FULL 6 PM_FPU_FMA 7 PM_FPU_IDLE` For a POWER4 event group name, the format is event_group_name. For example: `pm_hpmcount1`
HPM_flags.env	File containing environment variable/value pairs used for the computation of derived metrics. For example: `HPM_L2_LATENCY 12 HPM_EVENT_SET 5`

libHPM_events

User-supplied event set file. This file does not take precedence over the command lines specified with the -s option. The format for a POWER3/PowerPC 604 RISC Microprocessor counter/event pair is counternumber eventname. For example:

0 PM_LD_MISS_L2HIT 
1 PM_TAG_BURSTRD_L2MISS 
2 PM_TAG_ST_MISS_L2 
3 PM_FPU0_DENORM 
4 PM_LSU_IDLE 
5 PM_LQ_FULL 
6 PM_FPU_FMA 
7 PM_FPU_IDLE

For a POWER4 event group name, the format is event_group_name. For example:

pm_hpmcount1

HPM_flags.env

File containing environment variable/value pairs used for the computation of derived metrics. For example:

HPM_L2_LATENCY 12 
HPM_EVENT_SET  5

The following output files are used.

Item	Description
file	File specified with the -o option for hpmstat output results.