Skip to main content

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:

  1. Enter the following command:

    DO ^PERFMON
    
    
  2. 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 between collections (default = 10)

  • sample_time — number of seconds a collection should last (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 Report
    Metric 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 ObjectScript lines
    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:

    • XML – for Microsoft Excel XML markup suitable for import into Excel (.xml file)

    • HTML – for an HTML page (.html file)

    • CSV

  • 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, D=Database, I=Incoming or O=Outgoing node
Sort ('P', 'R', 'G', 'D', 'I' or 'O'): g
Format may be: P=Print, D=Delimited data, X=Excel XML, H=HTML
Format ('P', 'D', 'X', 'H'): 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, D=Database, I=Incoming or O=Outgoing node
Sort ('P', 'R', 'G', 'D', 'I' or 'O'): p
Format may be: P=Print, D=Delimited data, X=Excel XML, H=HTML
Format ('P', 'D', 'X', 'H'): p
File name: perfmonC.txt
 
 
 
FeedbackOpens in a new tab