MONITOR SAMPLE

Read syntax diagramSkip visual syntax diagram MONitor SAMPle ENableDISableALLAPPLdataALLUSERIDuseridI/OALLCLassclassDEVicerdevrdev1-rdev2TYpetypeVOLumeCPVOLvolidISFcNETworkPROCessorCPUMFC1SSISTORageSUBINTervalALLAPPLdataI/OISFcNETworkPROCessorSSISTORageUSERUSERALLUSERIDuseridCONFIGLIMITnMINutesSECondsSIZEnINTervalnMINutesSECondsSUBINTervalnSECondsRATEnSECondsSTOPSTArtSTOP
Notes:
  • 1 CPUMFC is valid only with the DISABLE keyword.

Authorization

Privilege Class: A, E

Purpose

Use MONITOR SAMPLE to establish or modify a profile for collecting single sampleStart of change, subinterval sample,End of change and high-frequency sample data. This command can also be used to begin or end sample monitoring.

SingleStart of change and subintervalEnd of change sample data are a set of counters and data that characterize a system operation. High-frequency sample data are a set of counters and data that characterize the system at the moment the data is sampled.

The sample profile lists the following:
  • Data domains and domain elements to be monitored
  • Rate at which high-frequency sample data is collected
  • Time interval at which sample data is reported
  • Start of changeThe subinterval at which samples are collected within an intervalEnd of change
  • Number of pages to be reserved for sample configuration records

Operands

ENable
enables the specified domains and their elements for sample data collection. Sample data is collected only from those domains that have been enabled. ENABLE is the default.
Note: The MONITOR domain and the SYSTEM domain are always enabled for sample data monitoring.
DISable
disables the specified domains or their elements from monitoring.
Note: The MONITOR domain and the SYSTEM domain cannot be disabled from sample data collection.
ENable ALL
DISable ALL
specifies that all domains and all their elements are to be enabled or disabled for Start of changesingle and subintervalEnd of change sample-data collection. This includes the following domains:
  • APPLDATA (all authorized users)
  • I/O (all devices)
  • ISFC
  • NETWORK
  • PROCESSOR
  • SSI
  • STORAGE
  • USER (all users)
Note: SYSTEM and MONITOR domains are enabled for sample monitoring at all times. For SUBINTERVAL, ENABLE ALL only enables domains that are enabled for single sample data collection.
ENable APPLdata
DISable APPLdata
specifies that the APPLDATA domain is to be enabled or disabled for sample data collection. APPLDATA domain is where CP collects data generated by an application program in a virtual machine. The virtual machine issues DIAGNOSE X'DC' START to declare a buffer from which CP can collect the information. For information on DIAGNOSE Code X'DC' – Control Application Monitor Record Collection in z/VM: CP Programming Services.
APPLdata ALL
specifies that all authorized users are to be enabled or disabled for sample monitoring in the APPLDATA domain. To be authorized for monitoring in the APPLDATA domain, the user's directory entry must contain an OPTION APPLMON statement.
APPLdata USERID userid
specifies a list of users to be enabled or disabled for sample monitoring in the APPLDATA domain. The userid is a list of one or more user identifiers, separated by blanks, from whom data is collected.

Each user specified in this list must have the OPTION APPLMON statement in their directory entry. Users who do not have this statement in their directory entries are not enabled for this domain.

ENable I/O
DISable I/O
specifies that the I/O domain is to be enabled or disabled for sample data collection. An I/O domain is comprised of all real I/O devices. You may enable or disable all or selected I/O devices for the I/O domain. You can restrict them by device numbers, classes, types, or volumes.
I/O ALL
specifies that all real devices are to be enabled or disabled for sample data collection in the I/O domain.
I/O CLass class
specifies a list of device classes that are to be enabled or disabled for sample data collection in the I/O domain. class is a list of one or more device classes, separated by blanks. All real devices of the specified class or classes are monitored.

For a list of classes that can be specified in this command, and for a list of device types that each class supports, see Table 1.

I/O DEVice rdev
I/O DEVice rdev1-rdev2
specifies the real devices to be enabled or disabled for sample data collection in the I/O domain. You may specify the device number of a single device; you can also specify a list, a range of devices, or a combination of both. If you specify a range, all valid devices in the range, inclusively, are enabled or disabled. For additional information, see Specific Usage Notes for I/O.
I/O TYpe type
specifies a list of device types that are to be enabled or disabled for sample data collection. type is a list of one or more device types (such as the 3380), separated by blanks. For valid device types, see Table 1. All real devices of the specified type or types are monitored.
I/O VOLume volid
I/O VOLume CPVOL
specifies a list of volumes that are to be enabled or disabled for sample data collection. volid is a list of one or more volume identifiers, separated by blanks. If CPVOL is specified, all CP-owned volumes are to be enabled or disabled for monitoring. A CP-owned volume is any volume specified on the CP_OWNED statement in the system configuration file. For devices identified by DEVNO, you cannot use the VOLUME option of MONITOR. The VOLUME option can only be used for devices identified by VOLSER.
ENable ISFc
DISable ISFc
specifies that the ISFC domain is to be enabled or disabled for sample data collection. Data such as ISFC Transport end point status change or ISFC Logical Link Definition changes are recorded.
ENable NETwork
DISable NETwork
specifies that the NETWORK domain is to be enabled or disabled for sample data collection. Data such as the number of packets sent by and delivered to a virtual guest adapter are recorded.
ENable PROCessor
DISable PROCessor
specifies that the PROCESSOR domain, including the CPU-Measurement Counter Facility, is to be enabled or disabled for sample data collection. Data related to CPU usage such as system locks, simulation, and interprocessor signaling are collected.
PROCessor CPUMFC
specifies that collection of CPU-Measurement Counter Facility counters is to be disabled for counter sets requiring activation by CP. Sample data collection of the rest of the PROCESSOR domain is unaffected.

Collection of CPU-Measurement Counter sets for the Multithreading (MT) Facility is unaffected. Those counter sets are collected when multithreading is enabled and collection of monitor sample records in the PROCESSOR domain is enabled.

Note: The CPUMFC keyword is valid only with the DISABLE keyword.
ENable SSI
DISable SSI
specifies that the SSI domain will be enabled or disabled for sample data collection. Data collected for this domain includes z/VM® Single System Image (SSI) cluster state change synchronization activities and mode occupancy. The SSI operand cannot be specified if the z/VM system is not part of the z/VM SSI cluster.
ENable STORage
DISable STORage
specifies that the STORAGE domain is to be enabled or disabled for sample data collection. Status and utilization data of real, virtual, shared, and auxiliary storage are collected.
Start of changeENable SUBINTerval domainEnd of change
Start of changeDISable SUBINTerval domainEnd of change
Start of changeenables or disables the specified domains and their elements for subinterval sample-data collection. Enablement and disablement of subinterval sample-data collection is effective only after a domain is enabled by using the MONITOR SAMPLE ENABLE command.
One of the following domain options must be specified:
ALL
Enables or disables subinterval collection for all domains that are enabled for SAMPLE.
APPLDATA
Enables or disables subinterval collection of data that is generated by application programs in a virtual machine for all users that are enabled for SAMPLE.
I/O
Enables or disables subinterval collection for all devices that are enabled for SAMPLE.
ISFC
NETWORK
PROCESSOR
SSI
STORAGE
USER
Enables or disables subinterval collection for all users that are enabled for SAMPLE.
Note: The MONITOR domain and the SYSTEM domain are always enabled for subinterval sample data collection. Those domains cannot be disabled for subinterval sample-data collection.
End of change
ENable USER
DISable USER
specifies that the USER domain is to be enabled or disabled for sample data collection. A USER domain is comprised of all users. Data collected for this domain consists of user resource utilization and status data for all or selected users.
USER ALL
specifies that all users are to be enabled or disabled for sample data collection in the USER domain.
USER USERID userid
specifies a list of users that are to be enabled or disabled for sample data collection. userid is a list of one or more user identifiers, separated by blanks.
SAMPle CONFIG LIMIT n MINutes
SAMPle CONFIG LIMIT n SEConds
specifies the time limit that the configuration records remain in the CONFIG area of the saved segment before they are refreshed or zeroed.
SAMPle CONFIG SIZE n
specifies the size in 4 KB pages to be allocated in the saved segment for SAMPLE configuration records.
SAMPle INTerval n MINutes
SAMPle INTerval n SEConds
specifies the time interval at which the sample data is to be reported. MINUTES is the default. For additional information, see Specific Usage Notes for INTERVAL.
Start of changeSAMPle SUBINTerval nEnd of change
Start of changeSAMPle SUBINTerval n SECondsEnd of change
Start of changespecifies the subinterval sample duration in seconds. See Specific Usage Notes for SUBINTERVAL.End of change
SAMPle RATE n SECONDS
specifies the frequency at which the high-frequency sample data is to be sampled. The operand n is the length of time between high-frequency sampling. High-frequency sample data is a set of counters and data that represent the state of the system at the moment they are sampled.

High-frequency sampling is automatically activated whenever the MONITOR SAMPLE START command is issued, unless the RATE value has been previously set to STOP. For additional information, see Specific Usage Notes for RATE.

SAMPle RATE STOP
immediately terminates the sampling of high-frequency data. Data for the current interval is lost.
SAMPle STArt
starts sample monitoring for the domains and their elements specified in preceding MONITOR SAMPLE commands.

If no application is connected (with an active path) for sample data when the command is issued, sample recording is held pending. However, high-frequency sampling, if enabled, is started.

When recording is activated (that is, when there is a user connected with an active path for sample data), sample configuration records from the monitor domain are generated. Sample configuration records include information concerning the processor, storage, paging, real I/O configurations, and initial sample configuration settings.

SAMPle STOP
deactivates sample monitoring. Collection of single sample data and high frequency data are stopped. All data collected for the current interval are purged. The monitor sample profile is not affected by this command.
Note: Do not use this command to stop the MONWRITE utility. (See MONWRITE for more information.)

Usage Notes

(General)
  1. The following must be done to activate sample recording:
    • A saved segment must be defined and saved for the monitor
    • A virtual machine must load the monitor saved segment and connect to *MONITOR for sample data
    • A MONITOR START or MONITOR SAMPLE START command must be issued.

    If the START command is issued when no virtual machine is connected with an active path to *MONITOR for sample data, sample recording is held pending until there is a connection with an active path.

  2. The intervals for sample data collection start at the time the sample start command is issued. Monitor does not generate sample records unless there is at least one eligible monitor user for sample data. The following two examples satisfy the conditions to generate sample records.
    • Example 1
      1. MONITOR SAMPLE START is issued at 10:00 A.M. with 10-minute intervals.
      2. A user connects to *MONITOR at 10:05 A.M. to collect sample data. The sample configuration records are generated at the connect time (10:05 A.M.), and the first data records are generated at 10:10 A.M.
    • Example 2
      1. A user connects to *MONITOR at 10:00 A.M. to collect sample data.
      2. MONITOR SAMPLE START is issued at 10:05 A.M. with 10-minute intervals. The first sample data records are generated immediately after the sample configuration records are generated (at 10:05 A.M.). The next sample interval is at 10:15 A.M.
  3. It is possible for a user who connects to *MONITOR for sample data collection to receive two record notification messages—one for sample configuration followed by one for the sample data records. See Example 2 above.
  4. The sample configuration message might be delayed for a user who connects to *MONITOR to collect sample data, and in turn the sample data notifications are also delayed for the user.
    • If another user has already connected to *MONITOR to collect sample data and has not replied to the sample configuration message, the monitor regenerates the configuration records after the configuration area is free and sends a sample configuration message to the user who just connected to *MONITOR.
      Note: If the MONITOR SAMPLE START command is issued before any user is connected to *MONITOR, the first user connected to *MONITOR holds the configuration area. When that user issues an IUCV REPLY or the configuration time limit expires, the other users who are connected receive data notification for a new set of configuration records.
    • If a user's path to *MONITOR is quiesced (or at its IUCV message limit) when the sample configuration notification is sent, the user receives notification for a refreshed set of configuration records when the user resumes the path (or responds to one or more previous messages).
  5. Both event and sample monitoring can be active at the same time. The MONITOR SAMPLE START command only starts sample monitoring. To start both event and sample monitoring, use the MONITOR START command described in MONITOR START/STOP. Similarly, MONITOR SAMPLE STOP stops only sample monitoring while MONITOR STOP stops both event and sample monitoring.
Specific Usage Notes for I/O:
  1. Any overlapping of I/O devices can exist on a series of MONITOR SAMPLE commands on the I/O domain. For example, if the command: 
    monitor sample enable i/o type 3380
    is followed by: 
    monitor sample enable i/o class dasd
    all DASD are enabled for monitoring. If the command is then followed by: 
    monitor sample disable i/o type 3380
    monitoring ceases for all 3380 devices, but continues for all other types of DASD.
  2. A message is issued for any specified device that does not exist.
  3. Devices that are enabled but are found to be offline are monitored when varied online. A summary message is issued indicating how many devices are enabled for monitoring, and how many are offline.
  4. The VOLUME operand can be used only for volumes attached to the system, because CP associates a volume label to a device number only at the time it is attached. If it is desired to enable a DASD not attached to the system, it can be done by using the DEVICE option.
  5. The volume to be monitored is maintained by its device address. Enabling or disabling a volume for monitoring remains valid as long as its device address does not change. For example, if a volume is detached and a volume with the same label at a different address is attached, the volume must be enabled again to be monitored, and its previous device address disabled.
  6. A cache data record will not be created for a secondary device of a duplex pair.
Specific Usage Notes for PROCESSOR:
  1. The MONITOR SAMPLE ENABLE PROCESSOR command can be used to turn on collection of CPU-Measurement Counter Facility counters only if the machine supports the CPU-Measurement Counter Facility, the z/VM software recognizes and supports the counter first version number (CFVN) and counter second version number (CSVN) values reported by the hardware, and the partition is authorized for the basic counter set. Authorization is set either in the partition's activation profile or through the Change LPAR Security task on the Support Element. If one or more of these prerequisites is not met, z/VM does not activate the collection of CPU-Measurement Counter Facility counters. If all of these prerequisites are met, z/VM collects counters in the basic counter set, along with counters in the problem-state, crypto-activity, and extended counter sets, provided those counters are authorized. See the CPUMFC operand for an explanation of how the collection of these counter sets can be controlled.

    The MT-Diagnostic counter set is not controlled by the CPUMFC operand. This counter set is authorized, enabled, and activated only if the Multithreading Facility is enabled. Therefore it is always collected if the Multithreading Facility is enabled and the PROCESSOR domain is enabled for sample data monitoring.

  2. Message HCP6263I is displayed when CPU-Measurement Counter Facility counters are available on the machine but the basic counter set is not authorized for the partition.
  3. The CPU-Measurement Counter Facility counters are part of the PROCESSOR sample domain. However, you might want to run with the PROCESSOR sample domain enabled but with the CPU-Measurement Counter Facility counters turned off. With respect to the PROCESSOR domain, the MONITOR SAMPLE command has the following behaviors:
    1. MONITOR SAMPLE ENABLE PROCESSOR turns on the entire PROCESSOR sample domain including the CPU-Measurement Counter Facility counters.
    2. MONITOR SAMPLE DISABLE PROCESSOR turns off the entire PROCESSOR sample domain, including the CPU-Measurement Counter Facility counters.
    3. MONITOR SAMPLE DISABLE PROCESSOR CPUMFC turns off collection of CPU-Measurement Counter Facility counters but leaves the rest of the PROCESSOR sample domain enabled.
  4. For more information about CPU-Measurement Counter Facility counters and the contents and formats of the various counter sets, refer to Load-Program-Parameter and CPU-Measurement Facilities and CPU-Measurement Facility Extended Counters Definition accompanying the machine on which you are running.
Specific Usage Notes for INTERVAL:
  1. The valid range of values for INTERVAL is 6 to 3600 for SECONDS, and 1 to 60 for MINUTES. INTERVAL values must be specified in whole numbers.
  2. The default value of INTERVAL is one minute (60 seconds).
  3. If an interval is currently in effect, the new interval does not take effect until the next sample data record is produced.
  4. The SAMPLE INTERVAL value must be greater than or equal to the SAMPLE RATE value.
  5. It is possible that data may not be reported by the time the interval expires. This happens when it takes longer than an interval to collect the data. If this happens, the interval time should be adjusted to allow sufficient time to collect and report the data.
Specific Usage Notes for SUBINTERVAL:
  1. The SUBINTERVAL value must divide evenly into the INTERVAL value in seconds, must not result in more than 255 subintervals per interval, and must not be less than the high-frequency sample RATE or greater than the sample INTERVAL in seconds.
  2. When the INTERVAL value is set, the SUBINTERVAL value is reset to the new INTERVAL value in seconds if it does not divide evenly into that value or would result in more than 255 subintervals per interval. In this situation, informational message HCP6225I is produced.
  3. If subinterval sampling is currently in effect, a new SUBINTERVAL value does not take effect until the next INTERVAL sample is produced.
  4. In each sample interval, guests with subinterval sampling enabled receive a sample every SUBINTERVAL seconds; all other guests receive one sample per interval.

Specific Usage Notes for RATE:

  1. The valid range of value for RATE is .01 to 30 seconds. As many as two digits may be specified after the decimal point. Leading zeros are not required, and trailing zeros are not required after the decimal point.
  2. The default value of RATE is two seconds.
  3. If a rate is currently in effect, the new rate does not take effect until the current high-frequency rate has elapsed.
  4. The SAMPLE RATE value specified must be less than or equal to the SAMPLE INTERVAL value.
  5. The frequency of doing high-frequency sampling is determined by the RATE setting, however the creation of monitor records containing high-frequency data is controlled by MONITOR SAMPLE INTERVAL.

Specific Usage Notes for CONFIG SIZE:

  1. The default size reserved for sample configuration records when sample monitoring is started is 4096 pages.
  2. The MONITOR SAMPLE CONFIG SIZE can be issued only when sample monitoring is not active. To change the size after sample monitoring has been started, you must first stop sample monitoring.
  3. The minimum value for CONFIG SIZE is one 4 KB page.
  4. The maximum value for CONFIG SIZE is equal to the maximum number of pages that can be specified as a type SC range with the DEFSEG command, minus 1 page for sample data records.
    Note: The number of pages reserved must fit within the saved segment to be used by monitor. This check is made when monitoring is started (if someone is connected to *MONITOR and the saved segment is known) or when the first user connects after monitoring has been started.
  5. The value of CONFIG SIZE is preserved when monitoring is stopped.
  6. If while running monitor you experience missing or incomplete monitor records, the size of the sample configuration record area may not be large enough to record all of the system configuration data, especially if there are a large number of devices available on your system. To increase the size of the sample configuration record area, see the MONITOR SAMPLE CONFIG command.

Specific Usage Notes for CONFIG LIMIT:

  1. The CONFIG time limit is the amount of time a user can keep the configuration area in use.
  2. The default value for the CONFIG time limit is one minute.
  3. The minimum value for CONFIG time limit is one second.
  4. The maximum value for CONFIG time limit is 120 minutes.
  5. The CONFIG time limit value must be specified as a whole number.
  6. When the CONFIG time limit expires, CP:
    • In the EXCLUSIVE environment—stops monitoring and issues message HCP6239I.
    • In the SHARED environment—purges the configuration message, releases the corresponding saved segment pages, and issues message HCP6253I. Data recording continues.
  7. Configuration records are created and the CONFIG time limit enforced whenever:
    • Recording begins. (A MONITOR START command is issued and at least one user is connected, with an active path, for the type of monitoring being started.)
    • Recording is underway, and:
      • A user connects (with an active path) for that type of monitor data
      • The path of a user connected for that type of data becomes active
      • The user, whose path to *MONITOR was quiesced when *MONITOR tried to send a configuration notification message, issues IUCV RESUME
      • The user, whose path to *MONITOR was at its IUCV message limit when *MONITOR tried to send a configuration notification message, issues IUCV REPLY or REJECT to one or more previous messages from *MONITOR.
  8. CONFIG TIME LIMIT is preserved when monitoring is stopped.

Responses

The command, MONITOR SAMPLE START, can be issued before or after a user connects to *MONITOR to collect sample data.

Response 1:

MONITOR SAMPLE STARTED -- RECORDING IS ACTIVATED

- or -

MONITOR SAMPLE STARTED BY [userid] -- RECORDING IS ACTIVATED
As a result of the MONITOR SAMPLE START command, sample monitoring has successfully started. There is at least one user with an active path connected to *MONITOR for sample data collection.

This response is sent to the user that issued the command. If this user is not the system operator, the response containing [userid] is also sent to the system operator.

Response 2:

MONITOR SAMPLE STARTED -- RECORDING IS PENDING

- or -

MONITOR SAMPLE STARTED BY [userid] -- RECORDING IS PENDING
MONITOR SAMPLE START has been issued. Because there is no user with an active path connected to *MONITOR for sample data collection, sample monitoring is held pending. It shall remain pending until the first user is connected to *MONITOR for sample data collection.

This response is sent to the user that issued the command. If this user is not the system operator, the response containing [userid] is also sent to the system operator.

Response 3: 
MONITOR SAMPLE STOPPED

- or -

MONITOR SAMPLE STOPPED BY [userid]

MONITOR SAMPLE STOP has been issued and sample monitoring has been stopped.

This response is sent to the user that issued the command. If this user is not the system operator, the response containing [userid] is also sent to the system operator.

Response 4: 
Command complete
The MONITOR command has completed successfully.