Configure Perf Collection (CFGPFRCOL)

The Configure Performance Collection (CFGPFRCOL) command changes certain collection attributes and determines how Collection Services will manage data collection. Some attributes changed with this command will take effect immediately, while others will take effect the next time a collection object is created. See the parameter help to determine how each attribute will be handled. The Collection Services server job (QYPSPFRCOL) can be started or cycled by using the Start Performance Collection (STRPFRCOL) command.

Parameters

Keyword	Description	Choices	Notes
INTERVAL	Default interval	*SAME, 0.25, 0.5, 1.0, 5.0, 15.0, 30.0, 60.0	Optional, Positional 1
LIB	Collection library	Name, *SAME	Optional
DFTCOLPRF	Default collection profile	*SAME, *MINIMUM, *STANDARD, *STANDARDP, *ENHCPCPLN, *CUSTOM	Optional
CYCTIME	Cycle time	Time, *SAME	Optional
CYCITV	Cycle interval	1-24, *SAME	Optional
RETPERIOD	*MGTCOL retention period	Single values: *SAME, *PERM Other values: Element list	Optional
	Element 1: Number of units	1-720
	Element 2: Unit of time	*HOURS, *DAYS
ENBSYSMON	Enable system monitoring	*SAME, *YES, *NO	Optional
CRTPFRHST	Create historical data	*SAME, *YES, *NO	Optional
CRTDBF	Create standard database files	*SAME, *YES, *NO	Optional
CRTPFRSUM	Create standard summary data	Single values: *SAME, *NONE, *ALL, *NO, *YES Other values (up to 2 repetitions): *PFRSUM, *SYSMON	Optional
HSTITV	Historical data interval	*SAME, 0.25, 0.5, 1.0, 5.0, 15.0, 30.0, 60.0	Optional
HSTSUMRET	Historical summary retention	Integer, *SAME	Optional
CRTHSTDTL	Create historical detail data	*SAME, *YES, *NO	Optional
HSTDTLRET	Historical detail retention	Integer, *SAME	Optional
HSTFILTER	Historical detail data filter	Integer, *SAME, *ALL	Optional
CHGPMLIB	Change PM Agent library	*SAME, *YES, *NO	Optional
STDDTARET	Standard data retention (days)	Integer, *SAME, *PERM	Optional
SYSMONRET	System monitor data retention	Integer, *SAME, *PERM	Optional
SYSMONCGY	System monitor categories	Single values: *SAME, *SYSMONDFT Other values (up to 30 repetitions): Element list	Optional
	Element 1: Categories to process	Name, *APPN, *CMNBASE, *CMNSTN, *CMNSAP, *DISK, *DOMINO, *DPS, *EXTSTG, *HTTP, *IPCS, *JOBMI, *JOBOS, *JAVA, *LCLRSP, *LPAR, *POOL, *POOLTUNE, *RMVSTG, *SNA, *SNADS, *SYSBUS, *SYSCPU, *SYSINT, *SYSLVL, *SQL, *TCPBASE, *TCPIFC, *USRTNS, *WAS
	Element 2: Time interval (in minutes)	1, 0.25, 0.5, 1.0, 5.0

Default interval (INTERVAL)

Specifies the default collection interval (in minutes). This value is used by most data categories as the collection sample interval. When a category has a minimum or maximum interval size associated with it and it also uses the default collection interval, the default interval will be used as long as it does not conflict with those other settings. When there is a conflict, the minimum or maximum will be used. For example the maximum interval size is five minutes for *DISK and *IPCS. If the default collection interval is set to a value larger than five minutes, the category will still collect at five minute intervals. This change will take effect immediately.

*SAME

The value does not change. If the value has never been modified, the interval will be 15 minutes.

0.25

The default collection interval will be 15 seconds.

0.5

The default collection interval will be 30 seconds.

1.0

The default collection interval will be 1 minute.

5.0

The default collection interval will be 5 minutes.

15.0

The default collection interval will be 15 minutes.

30.0

The default collection interval will be 30 minutes.

60.0

The default collection interval will be 60 minutes.

Collection library (LIB)

Specifies the library where the management collection object (*MGTCOL) will reside. This change will take effect the next time a collection object is created. If you change the collection library, you should be aware of the folowing: PM Agent and collection services use the same collection library. PM Agent will not be able to process any data which was collected in the previous library. In addition collections will automatically be removed from the new library based on the standard collection file retention period you have specified.

*SAME

The value does not change. If the value has never been modified, the library will be QPFRDATA.

name

Specify the name of the library where the management collection object should be created.

Default collection profile (DFTCOLPRF)

Specifies the default collection profile. This determines which categories will be included in the system-level collection. This change will take effect the next time a collection object is created.

*SAME

The value does not change. If the value has never been modified, the default collection profile will be *STANDARDP.

*MINIMUM

The minimum data collection recommended. Includes the following categories: *SYSBUS, *POOL, *HDWCFG, *SYSCPU, *SYSLVL, *JOBMI, *JOBOS, and *DISK.

*STANDARD

The standard profile includes all categories which are typically needed by the IBM Performance Tools for i, with the exception of communications data. It includes all categories in the *MINIMUM profile, as well as the following categories: *POOLTUNE, *SUBSYSTEM, *SNADS, *LCLRSP, *APPN, *SNA, *TCPBASE, *USRTNS, *LPAR, *EXTSTG, *SYSINT, *RMVSTG, and *SQL. The category *DOMINO will be included if the product IBM Domino for i has been installed on the system. The category *HTTP will be included if the product IBM HTTP Server for i (powered by Apache) has been installed on the system.

*STANDARDP

The standard plus profile includes all categories which are typically needed by the IBM Performance Tools for i, including communications data. It includes all categories in the *STANDARD profile, as well as the following categories: *IPCS, *CMNBASE, *CMNSTN, *CMNSAP, *TCPIFC, and *DPS.

*ENHCPCPLN

The enhanced capacity planner profile includes all categories in the *STANDARDP profile, with the addition *INTPEX.

*CUSTOM

The custom profile includes categories as defined by the user. This profile must be defined using the Configure Collection Services task within the IBM Navigator for i.

Cycle time (CYCTIME)

Specifies the base time at which the Collection Services server job (QYPSPFRCOL) will end the current collection and begin collecting data in a new management collection object (*MGTCOL). This change will take effect immediately.

*SAME

The value does not change. If the value has never been modified, the cycle time will be midnight.

time

Specify the time of day at which the collector will cycle. Although the CL command allows you to enter a time value that contains seconds, Collection Services supports only the hour and minute to cycle. Any value entered for seconds is ignored.

Cycle interval (CYCITV)

Specifies the time period after which the Collection Services server job (QYPSPFRCOL) will end the current collection and begin collecting data in a new management collection object (*MGTCOL). This parameter controls the maximum amount of data (based on time) that will be stored in a single collection object. This value will take effect immediately.

*SAME

The value does not change. If the value has never been modified, the cycle interval will be 24 hours.

1-24

Specify the number of hours after which the collection will be cycled.

*MGTCOL retention period (RETPERIOD)

Specifies how long the management collection objects (*MGTCOL) should be retained on the system. The retention period is used to calculate an expiration date and time that is stored in the collection object. After the retention period has expired, the object will be automatically deleted by the Collection Services server job (QYPSPFRCOL). Expired collections are removed from the system each time a collection starts or cycles. Collection objects will be automatically deleted only when they exist in the system's configured collection library. This change will take effect immediately and will apply to the current and future collection objects.

Single values

*SAME

The value does not change. If the value has never been modified, the retention period will be 24 hours.

*PERM

The object will not be automatically deleted.

Element 1: Number of units

retention-time

Specify how long the management collection object should be retained in hours or days. The collection object may be retained for up to 30 days.

Element 2: Unit of time

Specify whether the retention-time value specified for the Number of units element should be treated as a number of hours or a number of days.

*HOURS

The retention period is specified in hours. The valid time period range is 1 through 720.

*DAYS

The retention period is specified in days. The valid time period range is 1 through 30.

Enable system monitoring (ENBSYSMON)

Specifies whether or not Collection Services provides support for system monitoring. A cycle is required for changes to take effect.

To support system monitoring, Collection Services will collect certain data categories more frequently than that configured for the profile collection and it will submit a second batch job (CRTPFRDTA2) to produce a second database file collection in support of system monitoring requirements.

The categories and the associated collection intervals can be configured via the SYSMONCGY parameter if you wish to change the system monitoring defaults. The system monitor file collection has the same name as the standard collection except it begins with an "R". Only files associated with the system monitoring categories are produced.

Collection services also support a unique retention period for system monitor data via the SYSMONRET parameter. Expiration is handled similar to standard data.

*SAME

The value does not change. If the value has never been modified, the system default value is *NO .

*YES

System monitoring support is enabled.

*NO

System monitoring support is not enabled.

Create historical data (CRTPFRHST)

Specifies whether or not Collection Services will create historical data when the collection is cycled. This change will take effect immediately.

If this option is enabled, Collection Services will submit the QYPSPFRHST batch job at cycle time to create historical data. This job will process the management collection object for the collection that just ended and populate the historical collection with the data from the management collection object.

The time interval used to create historical data can be configured via the HSTITV parameter if you wish to change the default.

The historical summary data retention period can be configured via the HSTSUMRET parameter if you wish to change the default.

The option to create historical detailed data can be configured via the CRTHSTDTL parameter if you wish to change the default.

The historical detailed data retention period can be configured via the HSTDLTRET parameter if you wish to change the default.

The historical detailed data filter can be configured via the HSTFILTER parameter if you wish to change the default.

*SAME

The value does not change. If the value has never been modified, the system default value is *NO.

*YES

Historical data is created.

*NO

Historical data is not created.

Create standard database files (CRTDBF)

Specifies whether or not to submit the Create Performance Data (CRTPFRDTA) job. This job will create the standard database file collection and process the data in the current management collection object as it is collected. The CRTPFRDTA job will end when the Collection Services server job (QYPSPFRCOL) ends or cycles. If this option is set to *YES, a new CRTPFRDTA job will be submitted for every management collection object (*MGTCOL) created. A cycle is required for changes to take effect.

*SAME

The value does not change. If the value has never been modified, the system default value is *YES.

*YES

The CRTPFRDTA job is submitted.

*NO

The CRTPFRDTA job is not submitted.

Create standard summary data (CRTPFRSUM)

Specifies whether or not to create additional summary type data for the standard database file collection. A cycle is required for changes to take effect.

Single values

*SAME

The value does not change. If the value has never been modified, the system default value is *NONE.

*NONE or *NO

Summary file data is not generated.

*ALL or *YES

All Summary file data is generated.

Other values (up to 2 repetitions)

*PFRSUM

This option creates additional logical files as supported by the CRTPFRSUM command to improve the SQL performance of functions like the Performance Data Investigator.

*SYSMON

This option causes additional system monitoring database files to be created with the standard database file collection. These files summarize various category data and are necessary to use the system monitoring perspectives within the Performance Data Investigator. Creating these files allows the use of those perspectives with standard data collections.

Historical data interval (HSTITV)

Specifies the time interval used to create historical data. This change will take effect immediately.

*SAME

The value does not change. If the value has never been modified, the interval will be 60 minutes.

0.25

The historical collection interval will be 15 seconds.

0.5

The historical collection interval will be 30 seconds.

1.0

The historical collection interval will be 1 minute.

5.0

The historical collection interval will be 5 minutes.

15.0

The historical collection interval will be 15 minutes.

30.0

The historical collection interval will be 30 minutes.

60.0

The historical collection interval will be 60 minutes.

Historical summary retention (HSTSUMRET)

Specifies the retention period for historical summary data.

The historical summary data retention period is used to determine how long Collection Services historical summary data is to exist. Historical summary data is stored in files starting with QAPMHM*. Historical summary data older than the retention period is deleted by the Collection Services server job (QYPSPFRCOL) the next time the collector is cycled.

The retention period is specified in months. Saving more than 1 month of historical summary data requires that PM Agent is active. If you do not start PM Agent, you can specify 1 month. If you do start PM Agent, you can specify 1 to 600 months.

*SAME

The value does not change. If the value has never been modified, the system default value is 12 months.

retention-time

The number of months historical summary data is retained before it becomes eligible to be deleted.

Create historical detail data (CRTHSTDTL)

Specifies whether or not Collection Services will create historical detailed data.

If this option is enabled, detailed data for the top contributors of each metric will be stored in the historical collection to be used as drill-down data. The number of top contributors is determined by the HSTFILTER parameter.

*SAME

The value does not change. If the value has never been modified, the system default value is *YES .

*YES

Historical detailed data is created.

*NO

Historical detailed data is not created.

Historical detail retention (HSTDTLRET)

Specifies the retention period for historical detailed data.

The historical detailed data retention period is used to determine how long Collection Services historical detailed data is to exist. Historical detailed data is stored in files starting with QAPMHD*. Historical detailed data older than the retention period is deleted by the Collection Services server job (QYPSPFRCOL) the next time the collector is cycled.

The retention period is specified in days. Saving more than 7 days of historical detailed data requires that PM Agent is active. If you do not start PM Agent, you can specify 1 to 7 days. If you do start PM Agent, you can specify 1 to 60 days.

*SAME

The value does not change. If the value has never been modified, the system default value is 7 days.

retention-time

The number of days historical detailed data is retained before it becomes eligible to be deleted.

Historical detail data filter (HSTFILTER)

Specifies the number of top contributors for each metric to be stored in the historical data collection to be used as detailed drill-down data.

*SAME

The value does not change. If the value has never been modified, the system default value is 20.

*ALL

Keep all detailed data.

detailed-filter

The number of of top uses of each metric to keep.

Change PM Agent library (CHGPMLIB)

Specifies whether or not to change the PM Agent library to match the library used by Collection Services.

This parameter is no longer supported. It exists solely for compatibility with the releases earlier than Version 5 Release 5 Modification 0 of the operating system.

Standard data retention (days) (STDDTARET)

Specifies the retention period for standard database file collections.

Standard database file collections consist of data that is normally created by the CRTPFRDTA job in the configured collection library. The collection name (begins with a "Q") is the same as the name of the *MGTCOL the data was exported from.

The standard file data retention period is used to determine how long standard database file collections should be retained on the system. When standard data in the configured collection library is older than the current retention period setting, it will automatically be deleted by the Collection Services server job (QYPSPFRCOL) the next time the collector is started or cycled.

The retention period is specified in days.

*SAME

The value does not change. If the value has never been modified, the system default value is 10 days.

*PERM

The standard database file collections are not automatically deleted.

retention-time

The number of days standard database file collections are retained before they become eligible to be deleted.

System monitor data retention (SYSMONRET)

Specifies the retention period for system monitor database file collections.

These collections are produced when system monitoring is enabled via the ENBSYSMON parameter. System monitor database file collections consist of data that is normally created by the CRTPFRDTA2 job in the configured collection library. Files produced are limited to those categories identified for system monitoring data. The collection name is the same as the name of the *MGTCOL the data was exported from except that it begins with a "R".

The system monitor retention period is used to determine how long system monitor database file collections should be retained on the system. When a system monitor data in the configured collection library is older than the current retention period setting, it will automatically be deleted by the Collection Services server job (QYPSPFRCOL) the next time the collector is started or cycled.

The retention period is specified in days.

*SAME

The value does not change. If the value has never been modified, the system default value is 2 days.

*PERM

The system monitor file collections are not automatically deleted.

retention-time

The number of days system monitor file collections are retained before they become eligible to be deleted.

System monitor categories (SYSMONCGY)

Specifies the categories used for system monitoring. Each category can have an independent collection interval. A cycle is required for changes to take effect.

There may be up to 10 category/interval element list combinations specified for this parameter.

Element 1: Categories to process

Single values

*SAME

The list does not change. If the value has never been modified, the system default value is *SYSMONDFT.

*SYSMONDFT

The category list is reset to those categories specifically supported for system monitoring. These include: *SYSLVL, *POOL, *DISK, *JOBMI, *JOBOS, *CMNBASE, and *HTTP. All are collected at 1 minute intervals.

Other values

category-name

Specify the names categories for system monitoring support.

Note: The *SYSLVL category must be included in the list.

Valid category names are:

  Name              Description
  -------------     ---------------------------
  *APPN             APPN
  *CMNBASE          Communications (base)
  *DISK             Disk storage
  *DOMINO           IBM Domino for i
  *DPS              Data port services
  *EXTSTG           External storage
  *HTTP             IBM HTTP Server for i (powered by Apache)
  *IPCS             Network server
  *JOBMI            Jobs (MI tasks and threads)
  *JOBOS            Jobs (operating system)
  *JAVA             Java
  *LCLRSP           Local response time
  *LPAR             Logical partition
  *POOL             Memory pool
  *POOLTUNE         Memory pool tuning
  *RMVSTG           Removable storage
  *SNA              SNA
  *SNADS            SNADS
  *SYSBUS           System bus
  *SYSCPU           System CPU
  *SYSINT           System internal data
  *SYSLVL           System-level data
  *SQL              SQL
  *TCPBASE          TCP/IP (base)
  *TCPIFC           TCP/IP (interface)
  *USRTNS           User-defined transaction data
  *WAS              Websphere Application Server

Element 2: Time interval (in minutes)

1.0

The collection interval will be 1 minute. for this category.

0.25

The collection interval will be 15 seconds for this category.

0.5

The collection interval will be 30 seconds . for this category.

5.0

The collection interval will be 5 minutes for this category.

Examples

Example 1: Configuring Default Interval and Collection Library

CFGPFRCOL INTERVAL(5) LIB(QMPGDATA)

This command will cause the default interval at which most sample data is collected to be changed immediately to 5 minutes. In addition, the library where data is collected will change to QMPGDATA the next time a management collection object (*MGTCOL) is created.

Example 2: Configuring Cycle Time and Cycle Interval

CFGPFRCOL CYCTIME(030000) CYCITV(6)

This command will change the cycle time and cycle interval of the collection. The base cycle time will be 3:00 a.m. and the collection will cycle every six hours from the base time. New management collection objects (*MGTCOL) will be created at the following times: 3:00, 9:00, 15:00, 21:00, 3:00, 9:00, and so on.

Example 3: Configuring Retention Period

CFGPFRCOL RETPERIOD(25 *DAYS)

This command will cause the current and future collection objects to be retained on the system for 25 days before being automatically deleted by the Collection Services server job (QYPSPFRCOL).

Example 4: Configuring Default Collection Profile and Create Database Files

CFGPFRCOL DFTCOLPRF(*STANDARD) CRTDBF(*YES)

This command causes changes that will take effect the next time a management collection object (*MGTCOL) is created. At that time, the collection profile will change to *STANDARD and the Create Performance Data (CRTPFRDTA) job will be submitted.

Example 5: Configuring System Monitoring Support

CFGPFRCOL ENBSYSMON(*YES) SYSMONCGY((*SYSLVL .25) (*DISK .5)
                                    (*JOBMI 1) (*JOBOS 1))

This command enables system monitoring support the next time the collection is cycled or the collector is started. Data associated with the *SYSLVL category is collected at 15 second intervals, *DISK category data is collected at 30 second intervals, and job data (*JOBMI and *JOBOS categories) is collected at one minute intervals.

The CRTPFRDTA2 job will be submitted creating a system monitor collection that includes only these categories. The QAPMSMSYS, QAPMSMDISK, QAPMSMJMI, and QAPMSMJOS files will also be produced.

Error messages

*ESCAPE Messages

CPF3CF2

Error(s) occurred during running of &1 API.

CPF9810

Library &1 not found.

CPF9820

Not authorized to use library &1.