Using and configuring supervised learning

The “supervised” learning service can help you avoid false positives by excluding certain data that PFA uses when making predictions of future behavior. To minimize the impact to check performance, only use EXCLUDED_JOBS for the conditions that cause you the most inconvenience. Instead, use other tuning parameters for the check such as STDDEV. A sample EXCLUDED_JOBS file ships in the /usr/lpp/bcp/samples/PFA directory. It is named EXCLUDED_JOBS and includes an example comment line. You can modify the file using the OEDIT command, and then use the f pfa,update command to have PFA read in the contents of the file and start to use it in during processing. Supervised learning applies to the following checks:

PFA_ENQUEUE_REQUEST_RATE
PFA_LOGREC_ARRIVAL_RATE
PFA_MESSAGE_ARRIVAL_RATE
PFA_JES_SPOOL_USAGE: For example, the JES spool usage check shows a certain job to have high spool usage because the job is frequently restarted. You want to exclude this job from check processing.

After PFA is installed, you can optionally use the following instructions to use the supervised learning support:

Create the EXCLUDED_JOBS file in the /config directory for each check for which you want jobs excluded and that supports supervised learning. You can copy the sample from /usr/lpp/bcp/samples/PFA/EXCLUDED_JOBS.
Add the jobs you want to be excluded.
If PFA has already been started, run the f pfa,update command to cause the EXCLUDED_JOBS file to be read for all checks.
If you have modified the STDDEV parameter for a check because it was receiving too many exceptions and you are now excluding the jobs that caused the exception, consider reducing the STDDEV parameter for those checks.
Note: There is an excluded job for the message arrival rate check. The PFA_MESSAGE_ARRIVAL_RATE: CONSOLE exclusion is hardcoded. Data for the job is not included in the check-specific processing.

The checks that support supervised learning use a z/OS® UNIX file with the name EXCLUDED_JOBS in the /config directory for the check. This directory is read at check initialization (when PFA starts) and when the modify PFA,update command is issued for the check. For example, find the list of excluded jobs for the PFA_MESSAGE_ARRIVAL_RATE in the /pfa_directory/PFA_MESSAGE_ARRIVAL_RATE/config/EXCLUDED_JOBS file.

If you are using PFA in a z/OS UNIX shared file system environment, each LPAR in the sysplex has a local pfa_directory in which a directory exists for each check. For each LPAR in the sysplex that needs to exclude jobs, the EXCLUDED_JOBS file must exist in the /config directory of the checks for which jobs should be excluded. To generically specify the system on which to exclude the job, use a system name containing a wildcard in the system name field in the EXCLUDED_JOBS file. You can then copy the file from the /config directory for a check on one LPAR to the /config directory for the same check on another LPAR.

The PFA EXCLUDED_JOBS file format is a simple, comma-separated value format as shown in Table 1. The row ends when a new line character is reached. Each field ends when a comma is reached although not all data is stored in memory.

Table 1. PFA EXCLUDED_JOBS file format
Field	Length	Format of field
Job name	8 characters maximum	The name of the job to exclude and is required. Both the job name and the system name must match at run time in order for the job to be excluded on this system. Wildcard characters are allowed. The * character is allowed in any position and denotes one or more characters. The ? character is allowed in any position and denotes one character.
System name	8 characters maximum	This field identifies the system to which this excluded job applies. This field is required. Both the job name and the system name must match at run time in order for the job to be excluded on this system. If this excluded job applies to all LPARs in the sysplex, specify ``. If the exclusion applies to multiple systems, but not to all systems in the sysplex, use wildcard characters: The `` character is allowed in any position and denotes one or more characters. The `?` character is allowed in any position and denotes one character.
Date and/or time of adding	A maximum of 16 characters are stored in memory	This field is a character string that provides usability so you can see when you added the exclusion. There is no specific format and is not used by the code other than to display it when you request it. The length is 16 characters to fit the date and time in a numerical format such as: `06/10/2009 03:45` If you do not require this field, you can skip it by only specifying the comma delimiter. If the field is longer than 16 characters, only the first 16 characters are stored in memory. No error message is issued for this situation because the text is still available in the file.
Reason for adding	A maximum of 35 characters are stored in memory	This field is merely a character string and provided for usability so you can see the reason for excluding the job or address space. There is no specific format and is not used by the code other than to display it when you request it. If this field is not required, it can be omitted. If it is longer than 35 characters, only the first 35 characters are stored in memory. No error message is issued for this situation because the text is still available in the file. The `f pfa,display` output displays the first 29 characters. All 35 characters are written to the config log. You can type more characters and they remain in the file, but only the first 35 are in memory.

Example: Valid input rows

JES2,*,06/10/2009 03:45:35,Exclude JES2 on all systems
TEST*,SYS1,Skip all of my test jobs on SYS1
DUMPSRV,*
CONSOLE,SYS1,06/10/2009 03:45:35
CONSOLE,SYS2,06/10/2009 03:45:35

Example: Input rows that are not valid:

JES234567,*,,This name was too long.
,,06/10/2009,Name and system are required

Note:

When processing encounters a row that is not valid, it disregards the row and issues an error message.
The code checks that the maximum number of characters for the job name and the system name are 8.
When processing encounters a duplicate job name and system name combination, it uses the first occurrence, ignores the subsequent occurrence, and issues a message.
The EXCLUDED_JOBS file supports comment lines. If a line starts with /* or #, processing ignores the line. No ending comment is necessary however, the comment lines as well as all lines must end in a new line character ‘15’x.