Setting up hardware event data collection

Hardware instrumentation services (HIS) is a function that collects hardware event data for IBM® System z10 or later machines.

Before you start the HIS data collection, you may first need to authorize to the sampling facilities and counter set types you want to use through the support element (SE) console. For information about how to set up the authorization of the sampling facilities and counter sets, see Support Element Operations Guide for your machine type on the Resource Link home page.

In addition, with the enhanced-monitor facility hardware released with z196 machines, the HIS function expands into a z/OS software event data collector that will be used by IBM for improved problem analysis. The z/OS event counters are viewed as an additional hardware counter set, and there is no authorization required to use the hardware.

The HIS function will not work if your z/OS operating system is running as a z/VM guest.

With HIS, you can either collect instrumentation data in z/OS UNIX files and SMF buffers through the HIS profiler, controlled through the MODIFY hisproc,BEGIN command, or you can collect instrumentation data dynamically through the HISSERV service. See HISSERV service overview. Both services require initialization of the HIS address space.

If you plan to collect sampling or load map files, you must have z/OS UNIX System Services active, and you must perform all of the steps in Steps for starting the HIS address space. If you only plan to collect hardware or software (or both) counter sets into SMF type 113 records (and not z/OS UNIX files), then you can perform only the required steps according to the following guidelines:

Step 1 is always required (RACF definition).
Step 2 is only required if creating z/OS UNIX output files.
Step 3 is only required if creating z/OS UNIX output files.
Step 4 is always required (SMF enablement), especially if not collecting z/OS UNIX output files, as this is the only alternative output.
Step 5 is always required.

Steps for starting the HIS address space

Follow these steps to set up hardware event data collection:

Define the HIS-started task to RACF.
To set up the HIS-started task to RACF, you must define a profile for it to the RACF generic resource class called STARTED by using the RDEFINE command.

Note: If the STARTED class is not active, RACLISTed, and GENERIC profile checking is not activated, use the RACF SETROPTS command to activate (CLASSACT), RACLIST, and GENERIC the STARTED class first before you can define a new profile to it. In most environments, this might already have been done. Therefore, you might not have to include the SETROPTS command to CLASSACT, RACLIST, and GENERIC the STARTED class. In this example, these SETROPTS commands are shown for completeness. Running these commands when the STARTED class is already activated has no effect.
Example 1: RACF commands to define HIS-started task to RACF:
```
//DAEMONS EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
  SETROPTS CLASSACT(STARTED)
  SETROPTS RACLIST(STARTED)
  SETROPTS GENERIC(STARTED)
  RDEFINE STARTED HIS.* STDATA(USER(HIS) TRUSTED(YES))
  SETROPTS RACLIST(STARTED) REFRESH
  SETROPTS GENERIC(STARTED) REFRESH
```

Define a user ID for the HIS started task with an OMVS segment that specifies:

Any UID
A default HOME directory

For example, you might define the user ID as follows:

adduser HIS omvs(uid(25) home('HIS'))

where UID(25) is the OMVS uid and /HIS is the default home directory.

Note: While OMVS access is required, there is no special authorization needed. Also, any directory can be used for the HOME directory.

Example 2: Defining a HIS user ID for the HIS started task:

//DAEMONS EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
   ADDUSER HIS OMVS(UID(12) HOME('/HIS'))
   SETROPTS NOCLASSACT(SECLABEL) NORACLIST(SECLABEL)
   ALTGROUP SYS1 OMVS(GID(0))

Example 3: RACF commands to perform steps 1 and 2 in one job:

//DAEMONS EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
  SETROPTS CLASSACT(STARTED)
  SETROPTS RACLIST(STARTED)
  SETROPTS GENERIC(STARTED) 
  RDEFINE STARTED HIS.* STDATA(USER(HIS) TRUSTED(YES))
  SETROPTS RACLIST(STARTED) REFRESH
  SETROPTS GENERIC(STARTED) REFRESH
  ADDUSER HIS OMVS(UID(12) HOME('/HIS'))
  SETROPTS NOCLASSACT(SECLABEL) NORACLIST(SECLABEL)
  ALTGROUP SYS1 OMVS(GID(0))

Create the HOME directory in a local z/OS UNIX file system by issuing the mkdir command under z/OS UNIX. Also assign read/write/exec authority (making a HIS data collection directory):
```
omvs
tso omvs
mkdir /HIS
```
In this example, /HIS will be the default directory where the HIS output file will be stored. IBM may request this data and the SMF records for problem diagnosis. This directory is used only for the HIS profiler.
Note: If you plan to capture lots of sample data, this output directory for HIS data needs to be large enough.
For sample data, a directory with 1 GB available is recommended. For more information about calculating the disk space for sampling output, see Sampling function output in a .SMP file.
If you would like SMF records also, enable SMF record type 113 using either the SET SMF or SETSMF command. For example, you might enable SMF record type 113 as follows:
1. Issue SET SMF=xx to select the SMFPRMxx parmlib member you want to update with information for SMF record type 113.
2. Reply to the message issued in response to the SET SMF=xx command to change any SMFPRMxx parameters. For example, you might reply with the following information:
```
nn,sys(type(113)),intval(01),maxdorm(0100)   
```
  Then, reply nn,U to continue.
This reply will prompt the system to collect type 113 records, give you one minute collection intervals, and the data will only stay in the buffers for one minute before being written to the MANA or MANB data set. You can change other SMFPRMxx parameters on the SET SMF command response or the SETSMF command. See z/OS MVS Initialization and Tuning Reference.
Start the HIS started task with the following command. A hisproc procedure is delivered in PROCLIB as member HIS.
```
START hisproc
```
This command does the following:
- Starts the hardware instrumentation services address space for the system
- Creates a new instrumentation started task, hisproc for the system
- Initializes the HISSERV service and allows profilers to request authorization and collect instrumentation data through the HISSERV interface.
See Starting hardware instrumentation services (HIS) for complete information about the START hisproc command.
Note that it is important to assign a sufficiently high dispatch priority to the instrumentation started task hisproc, so that the task can write sampling data to the .SMP output files in a timely manner.

Steps to use the HIS profiler for hardware data collection

To configure and start a run of data collection on a system, issue one of the following commands:
- If you want to collect sampling and counter counter-set data, issue the following command to configure and start a run of data collection on a system:
```
MODIFY hisproc,BEGIN 
```
  This data will be stored in the z/OS UNIX files and SMF data sets.
- If you want to collect counter-set data and only want the results to be output as SMF type 113 records (and not into a z/OS UNIX file), issue the following command to configure and start a run of data collection on a system:
```
MODIFY hisproc,BEGIN,CNTONLY,CNTFILE=NO
```
Note that you must explicitly start each run of hardware data collection.
You can specify in advance the duration of a run of data collection you want by using the DURATION parameter on the MODIFY hisproc,BEGIN command.

If you configure a new processor online in a system after you have already issued the MODIFY hisproc,BEGIN command to start a data collection run for that system, HIS will enable resources (counters/samplib) for that CPU. The system does not collect data on a processor that is configured offline.

Note that z/OS® IRD processor management can configure processors offline or online automatically. A processor is online at the start of the instrumentation run, but it might be configured offline (and sometimes online again) during the run. The system does not collect data on the offline processor.

See Starting, configuring, and stopping HIS data collection for complete information about the MODIFY hisproc command.
To explicitly stop a HIS profiler on a system, issue the following command:
```
MODIFY hisproc,END
```
Alternatively, you can use the DURATION parameter on the MODIFY hisproc,BEGIN command to specify when you want a data collection run to end.
The system writes all the collected data to the z/OS UNIX output files at the path specified and to the SMF data set that is set up by the installation, depending on the parameters provided on the F hisproc,BEGIN command.

You can also use the STOP hisproc command to stop a run of data collection. Note that if you use the STOP command, you must restart the address space again with the START command before starting the next run of data collection. However, use of the STOP command may result in a non-reusable address space; therefore, the MODIFY command is the preferred means for ending a run of data collection.

See Starting, configuring, and stopping HIS data collection for complete information about the MODIFY hisproc command.