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.

Examples

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