Monitoring System Performance Using ^PERFMON
^PERFMON is a Caché utility that controls the MONITOR facility.
The MONITOR facility provides performance data for the Caché system by collecting counts of events at the system level and sorting the metrics by process, routine, global, and network nodes. Since there is some overhead involved in collecting this data, you must specifically enable the collection of counters and collect data for a specific number of processes, globals, routines, and network nodes. Caché allocates memory at MONITOR startup to create slots for the number of processes, routines, globals, and nodes specified. The first process to trigger an event counter allocates the first slot and continues to add to that set of counters. Once the facility allocates all the available slots to processes, it includes any subsequent process counts in the Other slot. It follows the same procedure for globals, routines, and nodes.
You can review reports of the data while collection is in progress. When you stop collection, memory is de-allocated and the counter slots are gone. So, any retention of the numbers needs to be handled by writing the reports to a file (or a global). Data is given as rates per second by default, although there is also an option for gathering the raw totals. There are also functions which allow you to pause/resume the collection, and zero the counters.
The menu items available by running ^PERFMON correspond directly to functions available in the ^PERFMON routine, and the input collected is used to directly supply the parameters of these functions.
Similar functions that control the same MONITOR facility are available through the classes in the %Monitor.System package. For more information see Caché Application Monitor in the “Using Caché System Monitor” chapter of this guide and the “Examining Routine Performance Using ^%SYS.MONLBL” chapter of this guide.
Using ^PERFMON
You can use the ^PERFMON routine in two ways: running it interactively or calling its functions from your own routines. The menu items available from running ^PERFMON correspond directly to callable functions in the ^PERFMON routine; it uses the input it collects to directly supply the parameters of these functions. Each function returns a success or failure status (1 for success and a string consisting of a negative number followed by a comma and a brief message for failure).
The following is an example of running the ^PERFMON routine interactively from the terminal:
-
Enter the following command:
DO ^PERFMON
-
The following menu appears. Enter the number of your choice. Press Enter to exit the routine.
1. Start Monitor 2. Stop Monitor 3. Pause Monitor 4. Resume Monitor 5. Sample Counters 6. Clear Counters 7. Report Statistics 8. Timed Collect and Report Monitor is Stopped Enter the number of your choice:
Each of these menu options corresponds to a callable function in the routine. The following functions are available:
Because ^PERFMON and the line-by-line monitor routine ^%SYS.MONLBL share the same memory allocation, you can only run one of them at a time on a Caché instance. You see the following message if you try to run ^PERFMON and ^%SYS.MONLBL has started monitoring:
The Line-by-line Monitor is already enabled.
This must be stopped before ^PERFMON can be used.
Start
Turns on collection of the statistics.
Format:
status = $$Start^PERFMON(process,routine,global,database,network)
Parameters:
-
process — number of process slots to reserve (default = $$pcount (the number of processes in the process table))
-
routine — number of routine slots to reserve (default = 200)
-
global — number of global slots to reserve (default = 100)
-
database — number of database slots to reserve (default = 10)
-
network — number of network node slots to reserve (default = 5)
If you are running ^PERFMON interactively, it prompts you for each parameter value.
Status Codes:
Status code | Description |
---|---|
1 | Successful |
-1 | Somebody else is using Monitor |
-2 | Monitor is already running |
-3 | Memory allocation failed |
-4 | Could not enable statistics collection |
Stop
Stops collection of statistics.
Format:
status = $$Stop^PERFMON()
Status Codes:
Status code | Description |
---|---|
1 | Successful |
-1 | Somebody else is using Monitor |
-2 | Monitor is not running |
Pause
Momentarily pauses the collection of statistics to allow a consistent state for viewing data.
Format:
status = $$Pause^PERFMON()
Status Codes:
Status code | Description |
---|---|
1 | Successful |
-1 | Somebody else is using Monitor |
-2 | Monitor is not running |
-3 | Monitor is already paused |
Resume
Resumes collection of statistics that you previously paused.
Format:
status = $$Resume^PERFMON()
Status Codes:
Status code | Description |
---|---|
1 | Successful |
-1 | Somebody else is using Monitor |
-2 | Monitor is not running |
-3 | Monitor is already running |
Sample Counters
Starts a job to continuously Pause and Resume a collection, creating a periodic sampling of metrics. If wait_time = 0, the background job is stopped and collection is Paused.
Format:
status = $$Sample^PERFMON(wait_time,sample_time)
Parameters:
-
wait_time — number of seconds until collection pauses (default = 10)
-
sample_time — number of until collection resumes (default = 1)
Status Codes:
Status code | Description |
---|---|
1 | Successful |
-2 | Monitor is not running |
-8 | Sample job already running |
Clear
Clears all metric counters.
Format:
status = $$Clear^PERFMON()
Status Codes:
Status code | Description |
---|---|
1 | Successful |
-1 | Somebody else is using Monitor |
-2 | Monitor is not running |
Report
The report function gathers and outputs a report of metrics.
Format:
status = $$Report^PERFMON(report,sort,format,output,[list],[data])
Parameters:
-
report — type of report to output; valid values are:
-
G – for global activity
-
R – for routine activity
-
N – for network activity
-
C – for a custom report where you select the metrics to report
-
-
sort — grouping and sort order of report; valid values are:
-
P – to organize the report by Process
-
R – to organize the report by Routine
-
G – to organize the report by Global
-
D – to organize the report by Database
-
I – to organize the report by Incoming node
-
O – to organize the report by Outgoing node
-
-
format — output format; valid values are:
-
P – for a printable/viewable report (.txt file, no pagination)
-
D – for comma delimited data (.csv file) which can be read into a spreadsheet
-
X – for Microsoft Excel XML markup suitable for import into Excel (.xml file)
-
H – for an HTML page (.html file)
-
-
output — enter a file name, Return to accept the default file name displayed, or 0 (zero) for output to the screen
-
list — (for Custom report only) comma-separated list of metric numbers which specify what columns to include in the report; the following table lists the metrics available.
Metrics for Custom ^PERFMON ReportMetric Number Column Title Description 1 GloRef global references 2 GloSet global sets 3 GloKill global kills 4 TotBlkRd total physical block reads (sum of next seven counters) 5 DirBlkRd directory block reads 6 UpntBlkRd upper pointer block reads 7 BpntBlkRd bottom pointer block reads 8 DataBlkRd data block reads 9 BdataBlkRd big data block reads 10 MapBlkRd map block reads 11 OthBlkRd other block reads 12 DirBlkWt directory block writes 13 UpntBlkWt upper pointer block writes 14 BpntBlkWt bottom pointer block write 15 DataBlkWt data block writes 16 BdataBlkWt big data block writes 17 MapBlkWt map block writes 18 OthBlkWt other block writes 19 DirBlkBuf directory block requests satisfied from a global 20 UpntBlkBuf upper pointer block requests satisfied from a global buffer 21 BpntBlkBuf bottom pointer block requests satisfied from a global buffer 22 DataBlkBuf data block requests satisfied from a global buffer 23 BdataBlkBuf big data block requests satisfied from a global buffer 24 MapBlkBuf map block requests satisfied from a global buffer 25 OthBlkBuf other block requests satisfied from a global buffer 26 JrnEntry journal entries 27 BlkAlloc blocks allocated 28 NetGloRef network global refs 29 NetGloSet network sets 30 NetGloKill network kills 31 NetReqSent network requests sent 32 NCacheHit network cache hits Note:This counter is no longer available in the current network protocol. However, network cache hits can be calculated using the formula NetGloRef - NetGloSet - NetGloKill - NCacheMiss.
33 NCacheMiss network cache misses 34 NetLock network locks 35 RtnLine M commands 36 RtnLoad routine loads 37 RtnFetch routine fetches 38 LockCom lock commands 39 LockSucc successful lock commands 40 LockFail failed lock commands 41 TermRead terminal reads 42 TermWrite terminal writes 43 TermChRd terminal read chars 44 TermChWrt terminal write chars 45 SeqRead sequential reads 46 SeqWrt sequential writes 47 IJCMsgRd local IJC messages read 48 IJCMsgWt local IJC messages written 49 IJCNetMsg network IJC messages written 50 Retransmit network retransmits 51 BuffSent network buffers sent The global, routine, and network activity reports (indicated by the report parameter) display a predefined subset of this list.
-
data — type of data to report; valid values are:
-
1 – for standard rates/second
-
2 – for raw totals
-
Status Codes:
Status code | Description |
---|---|
1 | Successful |
-1 | Monitor is not running |
-2 | Missing input parameter |
-3 | Invalid report category |
-4 | Invalid report organization |
-5 | Invalid report format |
-6 | Invalid list for custom report |
-7 | Invalid data format |
The Report Examples section shows how to enter different values for the input parameters.
Collect
The timed collect and report function provides a fast automated snapshot of system performance by collecting metrics for a specified period (30 seconds by default), creating five basic reports and a process count, and formatting them together as either an Excel spreadsheet or an HTML page.
Format:
status = $$Collect^PERFMON(time,format,output)
Parameters:
-
time — number of seconds for data collection (default 30)
-
format — output format; valid values are:
-
X – for Microsoft Excel XML markup suitable for import into Excel (.xml file)
-
H – for an HTML page (.html file)
-
-
output — enter a file name, Return to accept the default file name displayed, or 0 (zero) for output to the screen
Status Codes:
Status code | Description |
---|---|
1 | Successful |
-1 | Somebody else is using Monitor |
-3 | Monitor is already running |
Report Examples
The following is an example of running a report of global statistics, gathered and sorted by global name and output to a file in the manager’s directory called perfmon.txt.
%SYS>Do ^PERFMON
1. Start Monitor
2. Stop Monitor
3. Pause Monitor
4. Resume Monitor
5. Sample Counters
6. Clear Counters
7. Report Statistics
8. Timed Collect & Report
Enter the number of your choice: 7
Category may be: G=Global, R=Routine, N=Network or C=Custom
Category ('G', 'R', 'N' or 'C'): g
Sort may be: P=Process, R=Routine, G=Global, I=Incoming or O=Outgoing node
Sort ('P', 'R', 'G', 'I' or 'O'): g
Format may be: P=Print, D=Delimited data
Format ('P' or 'D'): p
File name: perfmon.txt
Press RETURN to continue ...
The following is an example of running a custom report of statistics that correspond to metrics with the following numbers: 5,10,15,20,25,30,35,40,45,50. The counts are gathered and sorted by process ID and output to a file in the manager’s directory called perfmonC.txt.
1. Start Monitor
2. Stop Monitor
3. Pause Monitor
4. Resume Monitor
5. Sample Counters
6. Clear Counters
7. Report Statistics
8. Timed Collect & Report
Enter the number of your choice: 7
Category may be: G=Global, R=Routine, N=Network or C=Custom
Category ('G', 'R', 'N' or 'C'): c
List of field numbers: 5,10,15,20,25,30,35,40,45,50
Sort may be: P=Process, R=Routine, G=Global, I=Incoming or O=Outgoing node
Sort ('P', 'R', 'G', 'I' or 'O'): p
Format may be: P=Print, D=Delimited data
Format ('P' or 'D'): p
File name: perfmonC.txt