Usage Monitor Trace Facility

Trace Facility function

While accumulating program usage data intended for data base import, the Usage Monitor performs some basic data aggregation with counters being maintained so that multiple similar events can be represented by a single record with an associated event count. For those occasions where you want to track individual program management events and ascertain their precise chronology, the Usage Monitor Trace Facility can be employed to collect this information, with dynamically alterable filters without affecting the data collected for the data base.

Trace data flow

Trace data is written to a separate data set in real time so there is no increase in the volume of program usage data staged in virtual storage. You can trace events which are excluded from Usage Import processing.

Once a trace is active, a record is written for each event that matches the selection criteria. When no space remains in the output data set, the trace is terminated without affecting the main data collection. The output data set is deallocated by the Usage Monitor whenever tracing terminates.

Trace data is not affected by a collection repository switch or by writer task activity. Any active trace will be terminated when the Usage Monitor terminates.

Data collected by the Trace Facility

Tracing selection criteria is specified as one or more job name masks, one or more program name masks, or both. Tracing occurs if the job name matches any active job name mask, or if the 8-byte program name matches any active program name mask. Currently there is no trace filtering based on UNIX program names, but UNIX program events can be traced based on job name filtering.

The data collected for Usage Import contains several different record types, but the type with the largest number of records is usually the program usage detail record. It is this record type that is written as trace data. Each record is appended with a suffix which contains additional data not needed by Usage Import, such as the program event type and a STCK event timestamp.

Trace data set contents

Trace data is written sequentially using QSAM as each record presents. Because all records will have the same structure, fixed-length records are used. The Usage Monitor overrides the logical record length to the required value, and resets the block size to zero to ensure that the system-determined block size is used. Although the Usage Monitor does not compress this data by zipping it, the data can be compressed by using system-managed storage facilities where available.

While HZAIBRWZ (shipped in the SHZAEXEC library) is intended to be a general zip file browser (using the ISPF BRIF service), it does also function with unzipped data. The HZABRZIP program (which HZAIBRWZ calls) inserts a data item label line for Usage Monitor trace records in the display as a browsing aid, as it does with any recognized Usage Monitor or Inquisitor record.

Member HZASTRCD shipped in the SHZASAMP library contains assembler source describing the structure of Usage Monitor trace records.