amepat Command

Purpose

Active Memory™ Expansion Planning and Advisory Tool amepat reports Active Memory Expansion information and statistics as well as provides advisory report that assists in planning the use of Active Memory Expansion for an existing workload.

Syntax

amepat [{{[-c max_ame_cpuusage% ] | [-C max_ame_cpuusage ]}|[ -e startexpfactor [ :stopexpfactor [ :incexpfactor ] ]]}][{[ -t tgt_expmem_size]|[ -a ]}]

[ -n num_entries ] [-m min_mem_gain ] [-u minucomp_poolsize ]

[-v ] [ -N ] [-O proc=<processor implementation> ][{ [ -P recfile ] | [ Duration ] | [ Interval <Samples> ]}]

amepat [ -N ] [ -R recfile ] {[ Duration] | [ Interval <Samples>]}

Description

Active Memory Expansion Planning and Advisory Tool amepat serves two key functions:
  1. Workload Planning - The amepat can be run to determine a workload that would benefit from Active Memory Expansion, and also to provide a list of possible Active Memory Expansion configurations for a workload.
  2. Monitoring - When Active Memory Expansion is enabled, the amepat tool can be used to monitor the workload and Active Memory Expansion performance statistics.
The amepat can be started in two different modes:
  1. In the Recording mode amepat records systems configuration and various performance statistics into a user specified recording file.
  2. In the Reporting mode amepat analyzes the system configuration and performance statistics, collected in real time or from the user specified recording file, to generate workload utilization and planning reports.
Note: This tool is available from AIX® Version 6.1 with the 6100-04 Technology Level-SP2 release, or later.

Workload Planning

When considering using Active Memory Expansion for an existing workload, amepat can be used to provide guidance on possible Active Memory Expansion configurations for the workload. When amepat is run concurrently with an existing workload that is not using Active Memory Expansion, amepat monitors the memory usage, memory reference patterns, and data compressibility over a user-configurable time period of the workload. The tool then generate a report with a list of possible Active Memory Expansion configurations for the workload. The tool includes an estimate of the processor utilization impacts for the different Active Memory Expansion configurations.

amepat can be run on all versions of IBM® Power Systems™ supported by AIX 6.1. It includes systems using POWER4, POWER5, POWER6®, or POWER7® family processors.

There are two key considerations when running amepat to do workload planning: the time at which to run the tool and the duration to run the tool. To get the best possible results from the tool, the tool must be run during the period of peak utilization of the workload. It ensures that the tool captures peak of utilization and memory usage information of the workload.

To use amepat to generate a report for workload planning, a monitoring duration must be specified when starting amepat.

In addition to using amepat on workload that are not yet using Active Memory Expansion, amepat can also be run in LPAR’s where Active Memory Expansion is already enabled. When used in this mode, amepat it provides a report of other possible Active Memory Expansion configurations for the workload.

Note: amepat requires privileged access to do Workload Planning. When a user starts the tool without the required privilege then the Workload Planning Capability is disabled ( -N flag is turned on implicitly)

Monitoring

amepat can also be used to monitor the processor and memory utilization statistics (Disabling the workload planning capability). With this Monitoring capability, amepat just gathers processor and memory utilization statistics, does not gather the additional data required for generating the report for workload planning. Thus, Active Memory Expansion Modeling and Advisory reports are not generated.

When amepat is started without a duration or interval, amepat defaults to monitoring only capability, and amepat reports a snapshot of the LPAR’s memory, processor utilization.

amepat can be started with duration and run with Monitoring only capability using the -N flag. The -N flag disables the workload planning capability of this tool, thus disabling the data gathering process & reporting for workload planning.

Note: Both Recording and Reporting modes can be started with -N flag. The -N flag is supported both in Active Memory Expansion Enabled and Disabled Machines.

amepat Report

Following are the six different sections of report displayed by the amepat tool:

Command Information Section

The Command Information Section provides details about the arguments passed to the amepat tool, time of invocation, the total time the system is monitored and the number of samples collected.

System Configuration Section

The System Configuration Section provides details about the system configuration. The following table provides the complete list of information reported.

Item Description
Partition Name Node name from where amepat is started
Processor Implementation Mode The processor implementation mode, it can be,POWER4, POWER5, POWER6, and so on.
Number Of Logical CPUs The total number of logical processors configured and active in the partition.
Processor Entitled Capacity Capacity Entitlement of the partition, represented in the unit of number of physical processors.
Note: The physical processor units can be in fraction as well, for example, 0.5 physical processor.
Processor Max. Capacity Maximum Capacity this partition can have, represented in the unit of number of physical processors
Note: The physical processor units can be in fraction as well, for example, 0.5 physical processor.
True Memory The true memory represents real physical or logical memory configured for this LPAR.
SMT Threads Number of SMT threads configured in the partition. The value can be 1, 2 or 4.
Shared Processor Mode Indicates whether Shared Processor Mode is configured for this partition. The possible values are:
Disabled
Shared Processor Mode is not configured.
Enabled-Capped
Shared Processor Mode is enabled & running in capped mode.
Enabled-Uncapped
Shared Processor Mode is enabled & running in uncapped mode.
Active Memory Sharing Indicates whether Active Memory Sharing is Enabled or Diabled
Active Memory Expansion Indicates whether Active Memory Expansion is Enabled or Diabled
Target Expanded Memory Size Indicates the target expanded memory size in MegaBytes for the LPAR. The Target Expanded Memory Size is the True Memory Size multiplied by the Target Memory Expansion Factor.
Note: This get displayed only when Active Memory Expansion is enabled
Target Memory Expansion factor Indicates the target memory expansion factor configured for the LPAR.
Note: This get displayed only when Active Memory Expansion is enabled

System Resource Statistics

System Resource Statistics provides details about the system resource utilization from CPU/Memory Stand point. The following table shows various statistics related to system resource utilization

Item Description
CPU Util The Partition's processor utilization in the units of number of physical processors. The percentage of utilization against the Maximum Capacity is also reported.
Note: If Active Memory Expansion is enabled, the processor utilization due to memory compression / decompression is also included
Virtual Memory Size The Active Virtual Memory Size in MegaBytes. The percentage against the True Memory Size is also reported.
True Memory In-Use This is amount of the LPAR’s real physical (or logical) memory in MegaBytes. The percentage against the True Memory Size is also reported.
Pinned Memory This represents the pinned memory size in MegaBytes. The percentage against the True Memory Size is also reported.
File Cache Size This represents the non-computational file cache size in MegaBytes. The percentage against the True Memory Size is also reported.
Available Memory This represents the size of the memory available, in MegaBytes, for application execution. The percentage against the True Memory Size is also reported.
Note: For all the utilization metrics Average, Minimum and Maximum values get displayed if amepat is run with duration/interval.

Active Memory Expansion Statistics

Active Memory Expansion Statistics provides details about the Active Memory Expansion statistics. This section is only displayed if Active Memory Expansion has been enabled for the LPAR. The following table describes the various statistics that are reported

Item Description
AME processor Usage The processor utilization for Active Memory Expansion activity in units of physical processors. It indicates the amount of processing capacity used for memory compression activity. The percentage of utilization against the Maximum Capacity is also reported.
Compressed Memory The total amount of virtual memory that is compressed. This is measured in MegaBytes. The percentage against the Target Expanded Memory Size is also reported.
Compression Ratio This represents how well the data is compressed in memory. A higher compression ratio indicates that the data compresses to a smaller size. For example, if 4 Kilobyte of data can be compressed down to 1 Kilobyte, then the compression ratio is 4.0.
Deficit Memory Size The size of the expanded memory, in MegaBytes, deficit for the LPAR. This is only displayed if the LPAR has a memory deficit. The percentage against the Target Expanded Memory Size is also reported.
Note: The Active Memory Expansion Statistics section displays only when the tool is started in an Active Memory Expansion enabled machine. It also displays the average, minimum and maximum values of the statistics when the tool started with duration/ interval.

Active Memory Expansion Modeled Statistics

Active Memory Expansion Modeled Statistics provides details about the modeled statistics for Active Memory Expansion. The following table provides the information about the modeled statistics.

Item Description
Modeled Expanded Memory Size It represents the size of expanded memory that is used to produce the modeled statistics.
Average Compression Ratio It represents the average compression ratio of the in-memory data of the workload. This compression ratio is used to produce the modeled statistics.
Modeled Expansion Factor It represents the modeled target memory expansion factor.
Modeled True Memory Size It represents the modeled true memory size (real physical or logical memory)
Modeled Memory Gain It represents the amount of memory the partition can gain by enabling Active Memory Expansion for the reported modeled expansion factor
AME processor Usage Estimate It represents an estimate of the processor that would be used for Active Memory Expansion activity for the specified configuration. It estimates the amount of processing capacity that would be used for memory compression activity. The processor usage is reported in units of physical processors. The percentage of utilization against the Maximum Capacity is also reported.
Note: This is just an estimate and should only be used as guidance; the actual usage can be higher or lower depending on the workload.
Modeled Implementation It represents the processor implementation for which modeling is done. This is available only if the –O proc option is used.
Note: This section is displayed only when -N flag is not used & when run by a privileged user. The generation of Modeled statistics requires Operating System to do certain simulation operation; hence the actual duration of monitoring can be higher than the user specified monitoring time.

Recommendation

Recommendation provides details about the Active Memory Expansion configuration that would provide optimal benefits to the current running workload.

Note: The recommendations are purely done based on the behavior during the monitoring period of the workload and hence the recommendations provided can be used only as guidance. The actual statistics can vary based on the actual behavior in real time of the workload.
Note: Active Memory Expansion Modeled Statistics & Recommendation are used for Workload Planning. When -N is specified both these reports is not displayed. Active Memory Expansion Statistics is reported only when running in Active Memory Expansion Enabled System.

amepat can be started using the System Management Interface Tool (SMIT) smit amepat fast path to run this command.

Note: This command is restricted inside WPAR. When amepat is started without specifying duration or interval then the utilization statistics(System, AME) will not display any Average, Minimum, or Maximum values. It just displays the Current value. The processor utilization just displays the average from the system boot time.
Note: When the Active Memory Expansion is enabled, multiple pagesize support is disabled and only 4K pages are used.

Flags

Item Description
-a Specifies to auto-tune the expanded memory size for Active Memory Expansion Modeled Statistics. When this option is selected, the Modeled Expanded Memory Size is estimated based on the current memory usage of the workload (excludes the available memory size).
Note: The -a and -t options are mutually exclusive.
-c max_ame_cpuusage% Specifies the maximum Active Memory Expansion processor usage in terms of percentage to be used for producing the Modeled statistics & recommendation.
Note: The default maximum used is 15%. The -C and -c option cannot be specified together. The -c and -e options are mutually exclusive.
-C max_ame_cpuusage Specifies the maximum Active Memory Expansion processor usage in terms of number of physical processors to be used for producing the Modeled statistics and recommendation.
Note: The -C and -c option cannot be specified together. The -C and -e option are mutually exclusive.
-e startexpfactor:stopexpfactor:incexpfactor Specifies the range of expansion factors to be reported in the Active Memory Expansion Modeled Statistics section.
Startexpfactor
Starting expansion factor. This field is mandatory if -e is used.
Stopexpfactor
Stop expansion factor. If not specified then the modeled statistics is generated for the start expansion factor alone.
incexpfactor
Incremental expansion factor. Allowed range is 0.01-1.0. Default is 0.5. Stop expansion factor need to be specified to specify incremental expansion factor.
Note: The -e option cannot be combined with -C or -c options.
-m min_mem_gain Specifies the Minimum Memory Gain. This value is specified in Megabytes. This value is used in determining the various possible expansion factors reported in the Modeled Statistics & also influence the produced recommendations.
-n num_entries Specifies the number of entries that need to be displayed in the Modeled Statistics.
Note: When -e with incexpfactor specified then -n value is ignored.
-N Disable Active Memory Expansion Modeling (Workload Planning Capability)
-O proc=<processor implementation> Specifies the processor implementation for which modeling is done. You can specify the following processor versions:
  • P7 or p7
  • P7+ or p7+
  • ALL or all (Displays all current AME supported processors)
Note: The -O option cannot be specified with the –R option.
-P recfile Process the specified recording file and generate report.
-R recfile Record the active memory expansion data in the specified recording file. The recorded data can be post processed later using the -P option.
Note: Only -N option can be combined with -R.
-t tgt_expmem_size Specifies the Modeled Target Expanded Memory Size. This makes the tool to use the user specified size for modeling instead of the calculated one.
Note: The -t and -a options are mutually exclusive.
-u minuncompressedpoolsize Specifies the minimum uncompressed pool size in Megabytes. This value over-rides the tool calculated value for producing Modeled Statistics.
Note: This flag can be used only when Active Memory Expansion is disabled.
-v Enables Verbose Logging. When specified a verbose log file is generated, named as amepat_yyyymmddhmm.log, where yyyymmddhmm represents the time of invocation.
Note: The verbose log also contains detailed information on various samples collected and hence the file will be larger than the output generated by the tool.
Duration Duration represents the amount of total time the tool need to monitor the system before generating any reports.
Note: When duration is specified interval/samples cannot be specified. The interval & samples will be determined by the tool automatically. The actual monitoring time can be higher than the duration specified based on the memory usage and access patterns of the workload.
Interval <Samples> Interval represents the amount of sampling time, Samples represents the number of samples need to be collected.
Note: When interval, samples are specified, duration is calculated automatically as (interval x Samples). The actual monitoring time can be higher than the duration specified based on the memory usage and access patterns of the workload.
Notes:
  1. The default behaviour of the amepat command on a modeling report would be as follows:
    • When the amepat command is run on POWER7 or earlier processor implementations, the default modeled processor implementation is POWER7.
    • When the amepat command is run on a processor implementation later than POWER7, the default modeled processor is the same as the processor implementation where it runs.
  2. When AME is enabled, the -O proc option can be used to model processors equal or newer than the processor implementation where the amepat command is running.
  3. The amepat command facilitates the user to provide minimum and/or maximum values for certain flags (like the -e flag) that helps alter the modeling behavior. The specified values are taken as suggested values by the amepat command. The amepat command overrides these values if they are not within the permissible ranges determined by the command during its course of execution.

Exit Status

Item Description
0 The command completed successfully.
>0 An error occurred.
ATTENTION: RBAC users and Trusted AIX users: 

This command can perform privileged operations. Only privileged users can run privileged operations.

Examples

  1. To display Active Memory Expansion Monitoring only report, enter:r:
    amepat
  2. To monitor the workload, for the duration of 16 minutes with 8 minute sampling interval and 2 samples, generate report for Workload Planning, enter:
    amepat 8 2
  3. To monitor the workload for a duration of 16 minutes and generate Active Memory Expansion report for Workload Planning with modeled memory expansion factors between 1.5 and 3 at 0.5 incremental factor, enter:
    amepat –e 1.50:3.00:0.5 16
  4. To monitor the workload for a duration of 16 minutes and generate Active Memory Expansion report for Workload Planning with capping the modeled AME processor usage to 30%, enter:
    amepat –c 30 16
  5. To monitor the workload for a duration of 16 minutes and generate Active Memory Expansion report for Workload Planning with starting modeled memory gain of 1000 MB, enter:
    amepat –m 1000 16
  6. To monitor the workload for a duration of 16 minutes and generate Active Memory Expansion report for Workload Planning by modeling a minimum uncompressed pool size 2000 MB, enter:
    amepat –u 2000 16 
  7. To use the recording mode of amepat to generate the recording file and generate reports with various filters, enter:

    Start Recording for a duration of 60 minutes.

    amepat –R myrecord_amepat 60
    Note: The recording mode will switch itself into background process.

    Generate Report for Workload Planning

    amepat -P myrecord_amepat

    Generate Report for Workload Planning with the modeled memory expansion factors ranging between 2 to 4 with 0.5 delta factor

    amepat -e 2.0:4.0:0.5 -P myrecord_amepat

    Generate Monitoring only report

    amepat -N -P myrecord_amepat
  8. To disable Workload Planning Capability & monitor the system for 30 minutes, enter:
    amepat -N 30