Usage Monitor Trace Facility

Trace Facility function

While accumulating program usage data intended for database 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 used to collect this information, with dynamically alterable filters and 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. It is even possible to trace events which are excluded from Usage Import processing.

Once a trace is active, a record will be written for each event that matches the selection criteria. When no space remains in the output data set, the trace will be 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 will occur 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 will be written sequentially using QSAM as each record presents. Because all records will have the same structure, fixed-length records are used. The Usage Monitor will override the logical record length to the required value and will reset the block size to zero to ensure that the system-determined block size is used. Although the Usage Monitor will 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) will insert 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.