lparstat Command

Purpose

Reports logical partition (LPAR) related information and statistics.

Syntax

lparstat {-i [ -W | -x | -s | -P | start of change-Nend of change ] | -W | -s | -P | start of change-uend of change | start of change-Nend of change | -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 can be performed on an LPAR.
-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.
start of change-Nend of change start of changeDisplays 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.
end of change
-o Specifies the file name for the XML output.
-p Displays the 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.
start of change-uend of change start of changeDisplays 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.end of change
Note: If Pool Utilization Authority (PUA) is not available, the app column is not displayed.

Examples

  1. To get the default LPAR statistics, enter the following command:
    lparstat 1 1 
  2. To get default LPAR statistics with summary statistics on Hypervisor, enter the following command:
    lparstat -h 1 1
  3. To get the information about the partition, enter the following command:
    lparstat -i
  4. To get detailed Hypervisor statistics, enter the following command:
    lparstat -H 1 1
  5. To get statistics about the shared memory pool and the I/O memory entitlement of the partition, enter the following command:
    lparstat -m
  6. To get statistics about I/O memory pools inside the LPAR, enter the following command:
    lparstat -me
  7. 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
  8. If the LPAR is running in dedicated mode and with 2 SMT threads the type would be in the following format:
    Type - Dedicated-SMT
  9. To calculate the memory compression statistics in an LPAR when Active Memory Expansion is enabled, enter the following command:
    lparstat -c 1 1
  10. 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.