Brian Wade's CP Monitor Collector

On this web page I give away and document a small package that helps with the task of collecting CP Monitor data (aka "MONWRITE data").

This collector offers several features beyond what the standard MONWRITE virtual machine can do, including:

  • Collecting for only a certain amount of time, then stopping;
  • Every N minutes, closing the current MONWRITE file and starting a new one;
  • Driving a user exit EXEC every time it closes a MONWRITE file, so you can react to the appearance of the new file;
  • Subordinating itself to another virtual machine, such as PERFSVM, that is in charge of determining the settings for the MONDCSS segment and CP Monitor;
  • Cleaning off the collection disk periodically, keeping only the N most recent files.
  • Cleaning off the collection disk periodically, discarding the F 4096 files more than N days old.

As shipped here, this collector is configured to:

  • Assume some other user is in charge of the settings of MONDCSS and of the starting and stopping of CP Monitor, and
  • Run endlessly, and
  • Start a new MONWRITE file every 60 minutes, and
  • Keep only the 24 most recent MONWRITE files.

These settings are appropriate for a system where z/VM Performance Toolkit is running. Perfkit assumes it is in charge of the settings of CP Monitor and of the starting or stopping of Monitor. These settings also provide a means to keep only the last day's worth of MONWRITE data, and to keep it in easily handled one-hour-sized files.

You can change the configuration by customizing the collector. More description is found below.

This web page tells how to set up and use my MONWRITE data collector, called LINMON.

Note: Before you proceed, please review our binary file movement page for special reminders about moving binary files from this web server to your CMS virtual machine.

New Installation

If you have never installed LINMON before, follow these instructions to accomplish a new installation.

  1. Create a virtual machine to collect MONWRITE data. In this sheet of instructions, I call said machine LINMON. This virtual machine will collect the MONWRITE data and log it out to disk. Here is a sample CP directory entry you can use as a starting point. USER LINMON PASSWORD 64M 256M EG IPL CMS PARM AUTOCR MACH XC OPTION QUICKDSP IUCV *MONITOR MSGLIMIT 255 NAMESAVE MONDCSS SHARE ABSOLUTE 3% SPOOL 000C 2540 READER * SPOOL 000D 2540 PUNCH A SPOOL 000E 1403 A CONSOLE 009 3215 T LINK MAINT 190 190 RR LINK MAINT 19D 19D RR LINK MAINT 19E 19E RR MDISK 191 3390 0303 0010 BKWLNX MR ALL ALL ALL MDISK 291 3390 0363 2500 BKWLNX MR ALL ALL ALL

    The important features in this directory are:

    • The EG privilege classes,
    • The PARM AUTOCR clause on the IPL card,
    • The OPTION QUICKDSP card,
    • The IUCV *MONITOR card,
    • The NAMESAVE MONDCSS card,
    • The SHARE ABSOLUTE card,
    • The 191 minidisk, which is where the code will reside, and
    • The 291 minidisk, which is where the collected MONWRITE data will reside.

    Of course, you will have to change the definitions of the 191 and 291 minidisks to ones appropriate for your system. Notes:

    • Change the passwords, of course.
    • Keep the 191 at 10 cylinders.
    • Create the 291 minidisk as large as you can get away with on your system. Use a 1-END minidisk on a 3390-9 or -27 if you have it. This minidisk is the disk to which LINMON will log out the collected MONWRITE data.

    Note: If you are a fan of the CMS Shared File System, you could put LINMON's A-disk in SFS and create a subdirectory to replace the 291 disk. Make sure you set LINMON's filespace limit high enough to handle the amount of MONWRITE data you will be collecting. You will have to customize PROFILE EXEC to access your collection directory at filemode B instead of accessing device 291. I run this package from SFS on my systems and it works great!

    Note: If you are running z/VM 6.2 or later and are using the Single System Image feature, you should make LINMON a multiconfiguration user, sometimes also known as an "identity user". For further instructions, refer to z/VM Planning and Administration.

  2. Log on to LINMON. CMS FORMAT the 191 and 291 disks. Log off of LINMON.

  3. Download VMARC MODULE from here. Save the downloaded file to your PC in binary, and then upload it to LINMON 191 in binary (FTP, perhaps).

  4. Download VMARC HELPCMS from here. Save the downloaded file to your PC in binary, and then upload it to LINMON 191 in binary (FTP, perhaps).

  5. Download LINMON VMARC from here. Save the downloaded file to your PC in binary, and then upload it to LINMON 191 in binary (FTP, perhaps).

  6. Log on to LINMON.

  7. Issue these CMS commands:
    PIPE < VMARC MODULE A | deblock cms | > VMARC MODULE A PIPE < VMARC HELPCMS A | deblock cms | > VMARC HELPCMS A PIPE < LINMON VMARC A | fblock 80 00 | > LINMON VMARC A F 80

    If any of the above commands issue warning or error messages or finish with a nonzero return code, you did not upload the files from your PC correctly. Do the uploads over again, making sure you use a technique that moves the file in binary and does not reblock records or introduce padding bytes.

  8. Issue this CMS command: VMARC UNPK LINMON VMARC A = = A ( OLDDATE REPLACE

    If this command issues warning or error messages or finishes with a nonzero return code, you did not upload LINMON VMARC from your PC correctly. Do the upload over again, making sure you use a technique that moves the file in binary and does not reblock records or introduce padding bytes.

  9. Issue this CMS command: EXEC LMINST

  10. Using XEDIT, create on LINMON 291 a file called MONDATA $MARKER. It doesn't matter what's in the file.

  11. (optional) Somewhere on your system you have established some XAUTOLOG commands, to autolog certain users at system IPL time. (Maybe you use AUTOLOG1's PROFILE EXEC for this.) However or wherever it is you accomplish such things, you might wish to add user LINMON to that list of userids, so that when you IPL your system, LINMON gets autologged.

At this point you have accomplished creating the LINMON virtual machine and loading my code into it. To finish your work, continue at heading "Completing The Installation", below.

Note: The MONWRITE MODULE distributed with this package is a replacement for the standard MONWRITE. My edition can do things the standard MONWRITE cannot do.

Refresh Installation

If you installed a previous version of LINMON and are merely upgrading, follow these refresh instructions.

  1. Download LINMON VMARC from here. Save the downloaded file to your PC in binary, and then upload it to LINMON 191 in binary (FTP, perhaps).

  2. Issue this CMS command: PIPE < LINMON VMARC A | fblock 80 00 | > LINMON VMARC A F 80

  3. Issue this CMS command: VMARC UNPK LINMON VMARC A = = A ( OLDDATE REPLACE

  4. If there is no file called MONSETUP COMMANDS on LINMON 191, issue this CMS command: COPYFILE MONSETUP $CMD A MONSETUP COMMANDS A ( OLDDATE REPLACE

At this point the refresh installation is complete.

A refresh installation does not write over your files PROFILE EXEC, COMMON SYNONYM, PROFILE XEDIT, MONSETUP OPTIONS, MONSETUP COMMANDS, MSUX EXEC, or MSDONE EXEC. We recognize you might have customized those.

Completing The Installation (required)

After you have done the basic installation steps above, you you must do a few more steps to complete the installation. Some of these steps are required, while others are optional. See the headings below.

Customizing MONSETUP OPTIONS (required)

You customize file MONSETUP OPTIONS to control how the collector works.

Before you begin customizing, you must decide whether you are going to let LINMON be in charge of the settings of CP Monitor, or rather should LINMON be subordinate to some other guest, such as PERFSVM, that is deciding the settings of CP Monitor. If you are running some other z/VM performance monitoring software, such as z/VM Performance Toolkit or a third-party z/VM performance monitoring product, you should probably configure LINMON to be subordinate to that other product.

Your file MONSETUP OPTIONS will just be a sequence of keywords, one keyword per line. The prologue of file MONSETUP $OPT describes what all the various keywords in file MONSETUP OPTIONS do.

Here are some example MONSETUP OPTIONS files. Probably one of these examples is exactly right for your situation.

When LINMON Is In Charge of CP Monitor

  • To let LINMON be in charge of the settings of MONDCSS and CP Monitor, and to put MONDCSS at pages A000-DFFF (160 MB line, for 64 MB), and to let LINMON pick the name of the MONWRITE file, and to let LINMON keep collecting in one single file until someone types MONWSTOP on its console, use: ===== Top of File ===== DCSSRANGE A000-DFFF ===== End of File =====

  • To let LINMON be in charge of the settings of MONDCSS and CP Monitor, and to put MONDCSS at pages A000-DFFF (160 MB line, for 64 MB), and to let LINMON pick the name of the MONWRITE file, and to collect for only one hour and then stop collecting, use: ===== Top of File ===== DCSSRANGE A000-DFFF COLLECTFOR 60 ===== End of File =====

  • To let LINMON be in charge of the settings of MONDCSS and CP Monitor, and to put the MONDCSS segment at pages A000-DFFF (160 MB line, for 64 MB), and to run the collector constantly, and to collect MONWRITE data in one-hour (60-minute) chunks, and to keep only the last 24 MONWRITE files collected, use: ===== Top of File ===== DCSSRANGE A000-DFFF COLLECTFOR 0 NEWFILE 60 KEEP 24 ===== End of File =====
When Another Product Is In Charge of CP Monitor

  • To let some other virtual machine be in charge of the settings of MONDCSS and CP Monitor, and to collect MONWRITE data until someone types MONWSTOP on LINMON's console, use: ===== Top of File ===== SUBORDINATE ===== End of File =====

  • To let some other virtual machine be in charge of the settings of MONDCSS and CP Monitor, and to collect MONWRITE data for only one hour and then stop collecting, use: ===== Top of File ===== SUBORDINATE COLLECTFOR 60 ===== End of File =====

  • To let some other virtual machine be in charge of the settings of MONDCSS and CP Monitor, and to run the collector constantly, and to collect MONWRITE data in one-hour (60-minute) chunks, and to keep only the last 24 MONWRITE files collected, use: ===== Top of File ===== SUBORDINATE COLLECTFOR 0 NEWFILE 60 KEEP 24 ===== End of File =====

Customizing MONSETUP COMMANDS (optional)

This file contains the CP MONITOR commands that the collector will issue when it starts CP Monitor, if in fact it is in charge of CP Monitor, that is, if you did not specify SUBORDINATE in the MONSETUP OPTIONS file.

My package ships with these settings for CP Monitor:

CP MONITOR EVENT ENABLE ALL CP MONITOR EVENT DISABLE SEEKS ALL CP MONITOR EVENT DISABLE SCHEDULER ALL CP MONITOR SAMPLE ENABLE ALL CP MONITOR SAMPLE INTERVAL 1 MIN CP MONITOR SAMPLE RATE 1 SEC CP MONITOR SAMPLE CONFIG SIZE 6144 CP MONITOR START PARTITION 4096

These settings are good for a system running with a 64 MB (16384 or x'4000' pages) MONDCSS.

If you want to change the commands in this file, you should probably go read the help for CP Monitor first and get familiar with how CP Monitor works. You should also go learn about the relationship between the size of MONDCSS and the CP MONITOR SAMPLE CONFIG and CP MONITOR START commands.

Customizing PROFILE EXEC (optional)

You might want to customize PROFILE EXEC to link and access local tools disks, or to collect to SFS instead of minidisks, or whatever.

Customizing PROFILE XEDIT (optional)

You might want to customize PROFILE XEDIT to your taste.

Customizing MSUX EXEC (optional)

My package drives MSUX EXEC every time it closes a MONWRITE file. If you want to put some postprocessing in here, go ahead.

Warning: Some customers have reported that if MSUX EXEC tries to drive a MODULE file, such as VMARC MODULE or FTP MODULE, bad things happen. If you stick with internal CMS commands such as COPYFILE, you should be fine.

All you have to do is COPYFILE MSUX $EXEC to MSUX EXEC and then customize away.

Customizing MSDONE EXEC (optional)

My package drives MSDONE EXEC when it is completely done collecting data. If you want to put some postprocessing in here, go ahead.

All you have to do is COPYFILE MSDONE $EXEC to MSDONE EXEC and then customize away.

Notes About the MONDCSS Segment

This collector will CP DEFSEG and CP SAVESEG the MONDCSS segment only if both SUBORDINATE is not specified and the MONDCSS segment does not exist. If these two conditions are both true, this collector will CP DEFSEG and CP SAVESEG the MONDCSS segment, putting the segment at the page range specified on the DCSSRANGE card.

If you are going to run this collector as not SUBORDINATE, you should take care to set the values on the DCSSRANGE card so that the MONDCSS segment does not overlap any page ranges of other segments LINMON uses. The DCSSRANGE card I ship in example file MONSETUP $OPT usually meets this criterion. You can use the command CP QUERY NSS MAP ALL to see what page ranges are already in use by the segments on your system.

Starting MONWRITE Data Collection

To start this collector, either:

  • CP FORCE LINMON and then CP XAUTOLOG LINMON, or
  • Log on to LINMON, get a "Ready;" prompt, and then press PF1 and hit ENTER.

The first couple of times you try this, you might consider using the second method, just to make sure that you see the console messages that indicate data collection has started.

Stopping MONWRITE Data Collection

To stop the collector, either:

  • CP FORCE LINMON, or
  • Log on to LINMON, type MONWSTOP, and hit ENTER, or
  • Log on to LINMON, press PF3, and hit ENTER.

Where the Data Lands

The data ends up on LINMON 291 in one or more CMS files. These files are suitable for input to z/VM Performance Toolkit.

Here is a screen shot of FILELIST, showing an example of what you might see on the LINMON 291 minidisk. The MONWRITE files are the ones of F 4096 format.

BKW FILELIST A0 V 169 Trunc=169 Size=27 Line=1 Col=1 Alt=0 Directory = VMHOME:MONWRITE.GDLVMGRN Cmd Filename Filetype Fm Format Lrecl Records Blocks Date Time D072408 T105750 Z1 F 4096 2618 2618 2008-07-24 11:36:36 GDLVMGRN MD000015 Z1 F 4096 4149 4149 2008-07-24 10:57:50 GDLVMGRN MSEXLOG Z1 V 73 252 4 2008-07-24 10:57:50 GDLVMGRN MD000014 Z1 F 4096 4127 4127 2008-07-24 09:56:50 GDLVMGRN MD000013 Z1 F 4096 4099 4099 2008-07-24 08:55:51 GDLVMGRN MD000012 Z1 F 4096 4080 4080 2008-07-24 07:55:33 GDLVMGRN MD000011 Z1 F 4096 3989 3989 2008-07-24 06:54:50 GDLVMGRN MD000010 Z1 F 4096 3977 3977 2008-07-24 05:53:50 GDLVMGRN MD000017 Z1 F 4096 4275 4275 2008-07-23 11:35:51 MONDATA $MARKER Z1 F 80 1 1 2003-12-04 10:48:26

To calculate how big a MONWRITE file is, divide the "Records" column by 256. The quotient is the file's size in MB.

How to Send Us MONWRITE Data

This topic gets so much attention that I have written a separate page about it.

Getting Help

If you need help, contact me.

This web page provides additional information on collecting monitor data.