Skip to main content

Monitoring System Performance Using ^PERFMON

^PERFMON is an ObjectScript utility that controls the MONITOR facility.

The MONITOR facility provides performance data for the InterSystems IRIS® data platform 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. InterSystems IRIS 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 Application Monitor in the “Using System Monitor” chapter of this guide and the “Examining Routine Performance Using ^%SYS.MONLBL” chapter of this guide.

Using ^PERFMON

You can run the ^PERFMON routine in two ways: interactively in the InterSystems Terminal, or by individual calls to its functions. All the options of ^PERFMON are available using either method.

^PERFMON contains the following functions:

Each function returns a status of success (1) or failure (a negative number, followed by a comma and a brief message).

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 an InterSystems IRIS 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.

Running ^PERFMON Interactively

The following is an example of running the ^PERFMON routine interactively from the Terminal:

  1. Enter the following command from the %SYS namespace:

    do ^PERFMON
  2. The following menu appears. Enter the number of your choice, or 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:
  3. Each option corresponds directly to a ^PERFMON function, and will prompt you for the necessary parameters. For example, entering 1 corresponds to Start function:

    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
     
    Monitor is Stopped
     
    Enter the number of your choice: 1
     
     
    Processes <24>:
    Routine <200>:
    Globals <100>:
    Databases <10>:
    Network nodes <5>:

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; input ? after specifying a custom report for a list of all possible metrics and their numbers.

    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, 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