lparstat Command

Purpose

Reports logical partition (LPAR) related information and statistics.

Syntax

lparstat {-i [ -W | -x | -s | -P | -N ] | -W | -s | | -P | -u | -N | -d | -m [ -e [ r | R ] [ -p[w] ] ] | [ -H | -h ] | [-X [-o filename ] ] [ -c ] | [-E [w ] ] = [ Interval [ Count ] ] [-L]}

Description

The lparstat command provides a report of LPAR related information and utilization statistics. This command provides a display of current LPAR related parameters and Hypervisor information, as well as utilization statistics for the LPAR. An interval mechanism retrieves numbers of reports at a certain interval.

The various options of lparstat command are exclusive of each other. The lparstat command with no options will generate a single report containing utilization statistics related to the LPAR since boot time. If the -h option is specified, the report will include summary statistics related to the Hypervisor. If an interval and count are specified, the above report display repeats for every interval seconds and for count iterations. interval and count cannot be used with the -i option. Only root users can run the -h and -H flags.

The interval parameter specifies the amount of time in seconds between each report. If you do not specify the interval parameter, the lparstat command generates a single report that contains statistics for the time since system startup and then exits. You can specify the count parameter only with the interval parameter. If you specify the count parameter, its value determines the number of reports that are generated and the number of seconds apart. If you specify the interval parameter without the count parameter, reports are continuously generated. Do not specify a value of zero to the count parameter.

When the lparstat command is invoked without the -i flag, two rows of statistics are displayed. The first row displays the System Configuration, which is displayed once when the command starts and again whenever there is a change in the system configuration. The second row contains the Utilization Statistics which will be displayed in intervals and again any time the values of these statistics are deltas from the previous interval.

If you specify the -X option, the lparstat command creates an XML file.

The following information is displayed in the system configuration row:

type: Indicates the partition type. The value can be either dedicated or shared.
mode: Indicates whether the partition processor capacity is capped or uncapped allowing it to consume idle cycles from the shared pool. Dedicated LPAR is capped or donating.
smt: Indicates whether simultaneous multithreading is enabled or disabled in the partition. If there are two SMT threads, the row is displayed as "on." However, if there are more than two SMT threads, the number of SMT threads is displayed.
lcpu: Indicates the number of online logical processors.
mem: Indicates online memory capacity.
Note: If Active Memory Expansion is enabled, mem specifies the expanded memory size configured for this LPAR. However, if the environment variable AME_MEMVIEW is set to TRUE, the mem value specifies the true memory size.
psize: Indicates the number of online physical processors in the pool.
ent: Indicates the entitled processing capacity in processor units. This information is displayed only if the partition type is shared.

If you specify the -m flag, the following information is displayed in the system configuration row:

lcpu: Indicates the number of online logical processors.
ent: Indicates the entitled processing capacity in processor units.
mem: Indicates online memory capacity.
Note: If Active Memory Expansion is enabled, mem specifies the expanded memory size configured for this LPAR. However, if the environment variable AME_MEMVIEW is set to TRUE, the mem value specifies the true memory size.
mpsz: Indicates the memory pool size of the pool that the partition belongs to (in GB).
iome: Indicates the I/O memory entitlement of the partition (in MB).
iomp: Indicates the number of I/O memory entitlement pools in the LPAR.

If you specify the -c flag, the following additional information is displayed in the system configuration row:

mmode

Indicates the system's memory mode. The values for mmode are:

Item	Description
Ded	Neither Active Memory Sharing nor Active Memory Expansion is enabled
Shar	Active Memory Sharing is enabled
Ded-E	Active Memory Expansion is enabled
Shar-E	Both Active Memory Sharing and Active Memory Expansion are enabled

mem

Indicates the expanded memory size of the LPAR.

tmem

Indicates the true memory size of the LPAR.

The following information is displayed in the utilization row:

%user

Indicates the percentage of the entitled processing capacity used while executing at the user level (application).

For dedicated partitions, the entitled processing capacity is the number of physical processors.

For uncapped partitions with a current physical processor consumption above their entitled capacity, the percentage becomes relative to the number of physical processor consumed (physc).

%sys

Indicates the percentage of the entitled processing capacity used while executing at the system level (kernel).

For dedicated partitions, the entitled processing capacity is the number of physical processors.

For uncapped partitions with a current physical processor consumption above their entitled capacity, the percentage becomes relative to the number of physical processor consumed (physc).

%idle

Indicates the percentage of the entitled processing capacity unused while the partition was idle and did not have any outstanding disk I/O request.

For dedicated partitions, the entitled processing capacity is the number of physical processors.

For uncapped partitions with a current physical processor consumption above their entitled capacity, the percentage becomes relative to the number of physical processor consumed (physc).

%wait

Indicates the percentage of the entitled processing capacity unused while the partition was idle and had outstanding disk I/O request(s).

For dedicated partitions, the entitled processing capacity is the number of physical processors.

For uncapped partitions with a current physical processor consumption above their entitled capacity, the percentage becomes relative to the number of physical processor consumed (physc).

The following statistics are displayed when the partition type is shared or dedicated-donating:

physc: Indicates the number of physical processors consumed.
vcsw: Indicates the number of virtual context switches that are virtual-processor hardware preemptions.

The following statistics are displayed only when the partition type is shared:

%entc: Indicates the percentage of the entitled capacity consumed. Because the time base over which this data is computed can vary, the entitled capacity percentage can sometimes exceed 100%. This excess is noticeable only with small sampling intervals.
lbusy: Indicates the percentage of logical processor(s) utilization that occurred while executing at the user and system level.
app: Indicates the available physical processors in the shared pool.
phint: Indicates the number of phantom (targeted to another shared partition in this pool) interruptions received.

The following statistics are displayed only when the -h flag is specified:

%hypv: Indicates the percentage of physical processor consumption spent making hypervisor calls.
hcalls: Indicates the average number of hypervisor calls that were started.

The following statistic is displayed only if the hardware can use the SPURR, and the processor is not running at nominal speed:

%nsp: Indicates the current average processor speed as a percentage of nominal speed.

The following statistic is displayed only if the turbo-mode accounting is disabled:

%utcyc: Indicates the total percentage of unaccounted turbo cycles.

The following statistics are displayed only when the -d flag is specified.

%utuser: Indicates the percentage of unaccounted turbo cycles in the user mode execution (application).
%utsys: Indicates the percentage of unaccounted turbo cycles in the kernel mode execution (kernel).
%utidle: Indicates the percentage of the unaccounted turbo cycles when the partition is idle and does not have any outstanding disk I/O requests.
%utwait: Indicates the percentage of the unaccounted turbo cycles when the partition is idle and has outstanding disk I/O requests.

If you specify the -m flag, the following metrics are displayed:

physb: Indicates that the physical processor is busy.
%entc: Indicates the percentage of the entitled capacity consumed. Because the time base over which this data is computed might vary, the entitled capacity percentage can sometimes exceed 100%. This excess is noticeable only with small sampling intervals.
vcsw: Indicates the number of virtual context switches that are virtual-processor hardware preemptions.
hpi: Indicates the number of hypervisor page-ins occurred.
hpit: Indicates the time that is spent waiting for hypervisor page-ins in milliseconds.
pmem: Indicates the physical memory that is allocated to the LPAR by hypervisor in GB.
iomin: Indicates the minimum entitlement of the I/O memory pool in MB.
iomu: Indicates the I/O memory entitlement of the LPAR in use in MB.
iomf: Indicates the free I/O memory entitlement in MB.
iohwm: Indicates the high water mark of I/O memory entitlement usage in GB.
iomaf: Indicates the total number of times that allocation requests for I/O memory entitlement pools have failed since system startup.

If you specify the -e flag with the -m flag, the following information about I/O memory entitlement pools is displayed:

iompn: Indicates the name of the I/O memory entitlement pool in MB.
iomin: Indicates the minimum entitlement of the I/O memory pool in MB.
iodes: Indicates the desired entitlement of the I/O memory pool in MB.
ioinu: Indicates the entitlement of the I/O memory pool in use in MB.
iores: Indicates the reserved entitlement of the I/O memory pool in MB.
iohwm: Indicates the high water mark of entitlement usage of the I/O memory pool in MB.
ioafl: Indicates the total number of times that allocation requests for this I/O memory entitlement pool have failed since system startup.

The following statistics are displayed only when the -c flag is specified:

%xcpu: Indicates the percentage of utilization (relative to the overall CPU consumption by the logical partition) for the Active Memory Expansion (AME) activity.
xphysc: Indicates the number of physical processors used for the Active Memory Expansion activity.
dxm: Indicates the size of the expanded memory deficit for the LPAR in MB.
pgcol: Indicates the logical real memory pages of the calling partition in megabytes that are coalesced during the active memory sharing activity.
mpgcol: Indicates the number of megabytes of the memory pages that are called by the memory pool of the coalesced partition during the Active Memory sharing activity. If the partition is not authorized to access the poolwide statistics, the metric shows zero.
ccol: Indicates the fraction of the CPU consumed in coalescing pages during the Active Memory sharing activity. If the partition is not authorized to access the poolwide statistics, the metric shows zero.

Note: Memory page coalescing is a transparent operation wherein the hypervisor detects duplicate pages, directs all the user read pages to a single copy, and reclaims the other duplicate physical memory pages.

Flags

Item	Description
-c	Adds the memory compression statistics of the LPAR to the default lparstat output. Note: This option is available only when Active Memory Expansion is enabled.
-d	Shows the detailed CPU utilization statistics. When the turbo-mode accounting is disabled, the lparstat command shows the breakdown by category of the unaccounted turbo cycles along with the dedicated, donating or shared utilization columns: %user, %sys, %idle, %wait, %entc, %idon, %bdon, %istol and %bstol.
-e	Displays information about the I/O memory entitlement pools of the LPAR. You can specify the -e flag only with the –m flag. See the metrics that are displayed when you specify the -m flag.
-E	Reports Scaled Processor Utilization Resource Register (SPURR) based utilization metrics if run on a SPURR-capable processor.
-h	Adds summary hypervisor statistics to the default lparstat output.
-H	Provides detailed Hypervisor information. This option basically displays the statistics for each of the Hypervisor calls. The various Hypervisor statistics displayed by this option, for each of the Hypervisor calls, are as below: Statistic Description Number of calls Number of Hypervisor calls made. Total Time Spent Percentage of total time spent in this type of call. Hypervisor Time Spent Percentage of Hypervisor time spent in this type of call. Average Call Time Average call time for this type of call in nano-seconds. Maximum Call Time Maximum call time for this type of call in nano-seconds.
-i	Lists details on the LPAR configuration. The various details displayed by the -i option are listed below: Name Description Partition Name Logical partition name as assigned at the HMC. Partition Number Number of this logical partition. Power® Save Mode Power saving mode of this logical partition. Online Virtual CPUs Number of CPUs (virtual engines) currently online. Maximum Virtual CPUs Maximum possible number of CPUs (virtual engines). Online Memory Amount of memory currently online. Maximum Memory Maximum possible amount of Memory. Type Indicates whether the LPAR is using dedicated or shared CPU resource and if the SMT is turned ON. The Type is displayed in the format [Shared \| Dedicated] [ -SMT ] [ -# ] The following list explains the different Type formats: Shared - Indicates that the LPAR is running in the Shared processor mode. Dedicated - Indicates that the LPAR is running in the dedicated processor mode. SMT[-#] - Indicates that the LPAR has SMT mode turned ON and the number of SMT threads is 2. If the number of threads is greater than 2, then the number of threads is also displayed. Mode Indicates whether the LPAR processor capacity is capped or uncapped allowing it to consume idle cycles from the shared pool. Dedicated LPAR is capped or donating. Entitled Capacity The number of processing units this LPAR is entitled to receive. Variable Capacity Weight The priority weight assigned to this LPAR which controls how extra (idle) capacity is allocated to it. A weight of `-1` indicates a soft cap is in place. Minimum Capacity The minimum number of processing units this LPAR was defined to ever have. Entitled capacity can be reduced down to this value. Maximum Capacity The maximum number of processing units this LPAR was defined to ever have. Entitled capacity can be increased up to this value. Capacity Increment The granule at which changes to Entitled Capacity can be made. A value in whole multiples indicates a Dedicated LPAR. Maximum Physical CPUs in System The maximum possible number of physical CPUs in the system containing this LPAR.
	(Details displayed by the -i flag, are as follows): Active Physical CPUs in System The current number of active physical CPUs in the system containing this LPAR. Active CPUs in Pool The maximum number of CPUs available to this LPAR's shared processor pool. Shared Physical CPUs in system The number of physical CPUs available for use by shared processor LPARs. Maximum Capacity of Pool The maximum number of processing units available to this LPAR's shared processor pool. Entitled Capacity of Pool The number of processing units that this LPAR's shared processor pool is entitled to receive. Unallocated Capacity The sum of the number of processor units unallocated from shared LPARs in an LPAR group. This sum does not include the processor units unallocated from a dedicated LPAR, which can also belong to the group. The unallocated processor units can be allocated to any dedicated LPAR (if it is greater than or equal to 1.0 ) or shared LPAR of the group. Physical CPU Percentage Fractional representation relative to whole physical CPUs that these LPARs virtual CPUs equate to. This is a function of Entitled Capacity / Online CPUs. Dedicated LPARs would have 100% Physical CPU Percentage. A 4-way virtual with Entitled Capacity of 2 processor units would have a 50% physical CPU Percentage. Minimum Memory Minimum memory this LPAR was defined to ever have. Minimum Virtual CPUs Minimum number of virtual CPUs this LPAR was defined to ever have. Unallocated Weight Number of variable processor capacity weight units currently unallocated within the LPAR group. Partition Group ID LPAR group that this LPAR is a member of. Shared Pool ID Identifier of Shared Pool of Physical processors that this LPAR is a member.
	(Details displayed by the -i flag, are as follows): Memory Mode Indicates whether the memory mode is shared or dedicated. If Active Memory Expansion is enabled, the memory mode also includes a new mode called Expanded. Total I/O memory entitlement The I/O memory entitlement of the LPAR. Variable memory capacity weight The variable memory capacity weight of the LPAR. Memory Pool ID The memory pool ID of the pool that the LPAR belongs to. Physical Memory in the Pool The physical memory present in the pool that the LPAR belongs to. Hypervisor Page Size The page size that hypervisor uses for the page-in and page-out of LPAR logical-memory pages. Unallocated Variable Memory Capacity Weight The unallocated variable memory-capacity weight of the LPAR. Unallocated I/O memory entitlement The unallocated I/O memory entitlement of the LPAR. Memory Group ID of LPAR The memory group ID of the Workload Manager group that the LPAR belongs to. Target Memory Expansion Factor The target memory expansion factor configured for the LPAR. Note: The target memory expansion factor is displayed when Active Memory Expansion is enabled. Target Memory Expansion Size The target expanded memory size for the LPAR. The target expanded memory size is the true memory size multiplied by the target memory expansion factor. Note: The target memory expansion size is displayed when Active Memory Expansion is enabled. Power Save Mode The power saving mode for the LPAR. Subprocessor Mode The subprocessor mode for the LPAR. You can specify the -i flag alone or with the -P, -W, -s, and -N flags.
-L	Displays whether the Live Partition Mobility (LPM) operation has been disabled for the server. The Hardware Management Console (HMC) should be consulted to determine if LPM has been disabled for the logical partition.
-m	Displays the statistics that are related to the following aspects: The logical memory The physical memory backing the logical memory of the LPAR The I/O memory entitlement of the LPAR The memory pool information on the pool that the LPAR belongs to For more information about the metrics that are displayed when you specify the -m flag, see the metrics section.
-N	Displays information about the EnergyScale modes of the system. You can specify only the -N flag or you can specify this flag along with the -i, -P, -W, and -s flags. Note: The details that are listed when you run the lparstat -N command might change based on the hardware configuration of the system and new firmware level of the system.
-o	Specifies the file name for the XML output.
-p	Displays information about the page coalescing statistics of the LPAR. You can specify the -p flag only with the -m flag. When you run the lparstat command with the -w and -p flags, the result displays all the metrics that are displayed by the -e flag in a single line.
-P	Displays information about the energy management tuning parameters. You can specify the -P flag alone or with the -i, -W, -s, and -N flags.
-r	Resets the high water mark of I/O memory entitlement once at the beginning of the command. You can use this flag only with the -m and -e flags.
-R	Resets the high water mark at the beginning of each monitoring interval. If you specify both the -r and -R flags, the -R flag takes effect.
-s	Displays LPAR information. The -s flag displays the following details: Service partition ID The service partition ID as assigned by the Hardware Management Console (HMC). Number of configured LPARs The number of LPARs that are configured on the HMC. You can specify the -s flag alone or with the -P, -i, -W and -N flags.
-t	Displays the time in the HH:MM:SS format when the command is run with intervals.
-W	Lists details of the workload partition (WPAR) configuration. If the command is run from the global environment, the WPAR Key value is 0. The -W flag displays the following details: WPAR Key WPAR static identifier. WPAR Configured ID WPAR dynamic identifier. WPAR Maximum CPUs Number of processors in a resource set. It displays the value of 0 if it is not restricted. WPAR Effective CPUs Number of processors in an effective resource set. It displays the value of 0 if it is not restricted. WPAR CPU Percentage WPAR processor-limit percentage. You can specify the -W flag alone or with -P, -i, -s, and -N flags.
-x	Lists the security mode settings for the LPAR.
-X	Generates the XML output. The default file name is lparstat_DDMMYYHHMM.xml, unless the user specifies a different file name with the –o option.
-u	Displays the expiration date of AIX® Update Access Key (UAK) of the system, the expiration date of the Firmware Update Access Key of the system, and the image date of the AIX operating system that is running.

Note: If Pool Utilization Authority (PUA) is not available, the app column is not displayed.

Examples

To get the default LPAR statistics, enter the following command:
```
lparstat 1 1 
```
To get default LPAR statistics with summary statistics on Hypervisor, enter the following command:
```
lparstat -h 1 1
```
To get the information about the partition, enter the following command:
```
lparstat -i
```
To get detailed Hypervisor statistics, enter the following command:
```
lparstat -H 1 1
```
To get statistics about the shared memory pool and the I/O memory entitlement of the partition, enter the following command:
```
lparstat -m
```
To get statistics about I/O memory pools inside the LPAR, enter the following command:
```
lparstat -me
```
If the LPAR is running in shared mode and with 4 SMT threads the type would be in the following format:
```
Type - Shared-SMT-4
```
If the LPAR is running in dedicated mode and with 2 SMT threads the type would be in the following format:
```
Type - Dedicated-SMT
```
To calculate the memory compression statistics in an LPAR when Active Memory Expansion is enabled, enter the following command:
```
lparstat -c 1 1
```
To get statistics about page coalescing inside an LPAR, enter the following command:
```
lparstat -mp
```

Files

Item	Description
/usr/bin/lparstat	Contains the lparstat command.