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.
- 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
where UID(25) is the OMVS uid and /HIS is the default home directory.adduser HIS omvs(uid(25) home('HIS'))
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:
- Issue SET SMF=xx to select the SMFPRMxx parmlib member you want to update with information for SMF record type 113.
- 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:
Then, reply nn,U to continue.nn,sys(type(113)),intval(01),maxdorm(0100)
- Start the HIS started task with the following command. A hisproc procedure is delivered in
PROCLIB as member HIS.
This command does the following:START hisproc
- 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.
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:
This data will be stored in the z/OS UNIX files and SMF data sets.MODIFY hisproc,BEGIN
- 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 hardware event data collection for complete information about the MODIFY hisproc command.
- 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:
- To explicitly stop a HIS profiler on a system,
issue the following command:
Alternatively, you can use the DURATION parameter on the MODIFY hisproc,BEGIN command to specify when you want a data collection run to end.MODIFY hisproc,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 hardware event data collection for complete information about the MODIFY hisproc command.