Caché Monitoring Guide
Monitoring System Performance Using ^PERFMON
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

^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:
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:
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:
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:
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