Start Monitoring

You can select which routines and processes to monitor and which metrics to collect. These characteristics of the collection remain until you stop the monitor. You provide monitoring collection information to the routine in the following order:

Routine Names – Enter a list of routine names to monitor. You can only select routines accessible from your current namespace. Do not use the leading ^ when entering the routine name; the names are case-sensitive. You may use asterisk (*) wild cards to select multiple routines. Press Enter twice after entering the last routine name to end the list.

Select Metrics to monitor – Enter the number of your choice of what type of metrics. The default is 1 for minimal metrics.

Select Metrics to monitor
  1) Monitor Minimal Metrics
  2) Monitor Lines (Coverage)
  3) Monitor Global Metrics
  4) Monitor All Metrics
  5) Customize Monitor Metrics
 
Enter the number of your choice: <1>

A description of what metrics are included for each option follows:

Minimal metrics — Monitors the metrics described in the following table.

Metric	Description
Metric#: 34 - RtnLine	Number of times a routine line is executed
Metric#: 51 - Time	Clock time spent in executing that line
Metric#: 52 - TotalTime	Total clock time for that line including time spent in subroutines called by that line

The time metrics are clock time and are measured in seconds.

Note:

Total Time for Recursive Code

When a routine contains recursive code, the TotalTime counter for the line which calls back into the same subroutine only records the time of the outermost call, which should be, in most cases, the actual time to run the recursive loop. Prior InterSystems IRIS releases accumulated the time for multiple iterations of the same code reporting times that may have seemed too large.

Lines — Monitors the number of times a routine line is executed (Metric#: 34 - RtnLine).
Global metrics — Monitors several global metrics (Metric# 1-26,34-36,51,52).
All metrics — Monitors all available metrics.
Customize metrics — Allows you to create a customized list of metrics to monitor. You can select any of the standard performance metrics supported by the %Monitor.System package classes. Enter a question mark (?) when prompted for the metric item number to see a list of available metrics. For example:
```
Enter the number of your choice: <1> 5
 
Enter metrics item number (press 'Enter' to terminate, ? for list)
 
Metric#: ?
1.) GloRef: global refs
2.) GloSet: global sets
.
.
.
34.) RtnLine: lines of ObjectScript
.
.
.
51.) Time: elapsed time on wall clock
52.) TotalTime: total time used (including sub-routines)
Metric#:
```
This example does not show the full list; it is best for you to retrieve the current list when you run the routine. See Line-by-line Monitor Programming Interface for a method of retrieving the list.

Note:

For all collections, the number of routine lines and time (minimal metrics) are always collected.

Select Processes to monitor – Enter the number of your choice as it appears in the menu. The default is 1 for all processes.
```
Select Processes to monitor
  1.) Monitor All Processes
  2.) Monitor Current Process Only
  3.) Enter list of PIDs
 
Enter the number of your choice: <1>
```
^%SYS.MONLBL does not currently provide a list or a way to select PIDs; however, you can use the ^%SS utility or the Processes page of the Management Portal (System Operation > Processes) to find specific process ID numbers.
```
Enter the number of your choice: <1> 3
 
Enter PID (press 'Enter' to terminate)
 
PID: 1640
PID: 2452
PID:
 
```
Press Enter twice after entering the last process ID to end the list.

Once you provide the necessary information, ^%SYS.MONLBL allocates a special section of shared memory for counters for each line per routine, and notifies the selected processes that monitoring is activated.

Note:

Since shared counters may be updated simultaneously by multiple processes and/or running processes may not start counting at exactly the same moment, there may be a slight loss of precision in the counters, resulting in counts being lower than expected.


Monitor started.
 
Press RETURN to continue ...

After starting the line-by-line monitor, the routine displays a more extensive menu. Line-by-line Monitoring Options describes each option on this extended menu.

Estimate Memory Requirements