docs.intersystems.com
Home  /  System Administration  /  Monitoring Guide  /  Monitoring InterSystems IRIS Using BMC PATROL


Monitoring Guide
Monitoring InterSystems IRIS Using BMC PATROL
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This appendix describes the interface between InterSystems IRIS™ and BMC PATROL.
BMC PATROL is a tool for monitoring and managing various software systems. InterSystems IRIS supplies PATROL extensions so that you can monitor and collect information about InterSystems IRIS.
This interface allows users to monitor metrics of one or multiple InterSystems IRIS systems from the PATROL Console. The interface requires that the PATROL daemon is running on the InterSystems IRIS system to collect and output the metric values and that the InterSystems IRIS knowledge module files (*.km) are loaded into the PATROL Console to read and display these values.
This appendix provides information on the following topics:
Running PATROL with InterSystems IRIS
Run the ^PATROL ObjectScript routine on each InterSystems IRIS installation that you want to monitor using the start and stop entry points, or by setting it to automatically run at system startup.
The routine starts a background process that outputs metrics to a file, patrol.dat, located in the InterSystems IRIS manager’s directory install-dir\Mgr (where install-dir is the InterSystems IRIS installation directory). The file is rewritten for each collection period, so the file size is static. The file also includes an identifying header and a time stamp so that the PATROL Console can determine that it is active and up-to-date.
There are two ways to run and configure PATROL in InterSystems IRIS:
Configure PATROL Settings
Automatic PATROL Startup — You can set an option to automatically start the PATROL daemon at InterSystems IRIS startup using the Management Portal:
  1. Navigate to the System > Configuration > Monitor Settings page of the Management Portal.
  2. Click Yes in the Start Patrol at System Startup setting box.
    When Yes, the connection to PATROL starts automatically whenever InterSystems IRIS starts up. The default is No. When you edit this setting, the InterSystems IRIS end of the PATROL interface immediately stops and starts.
  3. Click Save.
PATROL Arguments — From the same System > Configuration > Monitor Settings page of the Management Portal, you can also set the following PATROL settings:
By default, PATROL uses standard InterSystems IRIS system counters to generate metrics (for more information see InterSystems IRIS Metrics Used with BMC PATROL in this appendix). However, you can activate the extended counters, which use more system resources than the standard counters. To change the counters, use the following function before starting the ^PATROL routine:
$$Light^PATROL(n)
where n is:
To see which version is currently specified, in the Terminal, enter the following command:
%SYS>write $$Light^PATROL()
InterSystems IRIS PATROL Routine
InterSystems IRIS provides entry points to the ^PATROL routine to start and stop PATROL.
To start PATROL:
Do start^PATROL(display,process,timer)
The arguments are described in the following table:
Argument Description Default Management Portal Monitor Setting
display Display mode. The literals total, delta, or rate to indicate the type of numbers to output. total Patrol Display Mode
process How many processes for which to pass %SS statistics. 20 Patrol Top Processes to Monitor
timer Collection period in seconds. 30 Patrol Collection Interval Seconds
For example:
Do start^PATROL("total",20,30)
Sets the PATROL console to display the total statistic counts, since the collection started, for the top 20 processes; InterSystems IRIS sends the information every 30 seconds. The collection period argument is passed to the PATROL console so that the collection and display update are synchronized.
To stop PATROL:
Do stop^PATROL
InterSystems IRIS PATROL Knowledge Modules
The architecture of PATROL is based on the concept of knowledge modules. A knowledge module contains a set of commands, parameters to monitor, and actions used by PATROL. The InterSystems IRIS plug-in for PATROL consists of several knowledge modules to be loaded into the PATROL Console. These .km files are provided in the InterSystems IRIS Patrol directory, install-dir\Patrol.
Once these knowledge modules are loaded, the Console automatically attempts to discover InterSystems IRIS installations on all connected systems. The discovery process either searches the Registry on Windows platforms or parses the output from the iris list command on UNIX®/Linux platforms. For each InterSystems IRIS installation it finds it checks to see if the patrol.dat file exists in the InterSystems IRIS manager's directory and if the time stamp within that file is current. InterSystems IRIS installations which are currently reporting InterSystems IRIS metrics for PATROL appear in the PATROL Console.
Adding InterSystems IRIS Modules to PATROL
Included in the Patrol directory is the ISC_CACHE.kml file listing all of the InterSystems IRIS knowledge modules. Use the following procedure to load and activate the knowledge modules:
  1. From the PATROL Console File menu, click Load KM.
  2. Select the ISC_CACHE.kml file in the InterSystems IRIS Patrol directory, install-dir\Patrol.
  3. The ISC_CACHE module should appear in the Desktop tab of the Console in a few seconds.
  4. Right-click ISC_CACHE and choose Add Configuration from the KM Commands menu.
  5. In the Add Configuration dialog box, enter an instance name and the InterSystems IRIS installation directory.
  6. You may need to wait for, at most, 30 seconds (PATROL default sync period), before PATROL recognizes InterSystems IRIS statistics.
For more information you can consult the BMC Web site.
If any InterSystems IRIS installations are discovered on a system, then the main entry for InterSystems IRIS (the InterSystems IRIS class) appears under that system entry. Each InterSystems IRIS instance (each InterSystems IRIS configuration installed on that system) appears under the InterSystems IRIS class. Under each InterSystems IRIS instance are the general metric categories of Overview, Global, Routines, Disk Activity, Network, and Other.
For example:
- PATROLMainMap
  - TEST1
    - ISC_CACHE
      - ISC_Config_CACHE
        + ISC_DiskActivity
        + ISC_Global
        + ISC_Network
        + ISC_Other
        + ISC_Overview
        + ISC_Routine
The categories expand to show all the individual metrics. The metrics under Overview are gauges showing current levels. The others are graphs showing values over time.
Right clicking the InterSystems IRIS configuration allows the user to select InterSystems IRIS-specific commands, to either Remove Configuration or show a Process Status window.
Manually adding a configuration should not normally be necessary, since all InterSystems IRIS installations should be automatically discovered, but might be useful if there is a question or a problem with a specific installation.
Error messages from the InterSystems IRIS KMs may be output to the System Output window. Check these messages if you have questions about InterSystems IRIS installations that are not automatically discovered.
InterSystems IRIS Metrics Used with BMC PATROL
The list of metrics for InterSystems IRIS:
InterSystems IRIS PATROL Metrics
Category Metric
Overview Global Refs (gauge)
Global Sets, Reads, Kills (graph)
Net Global Refs (gauge)
Net Global Sets, Reads, Kills (graph)
Routine Lines (gauge)
Routine Loads (gauge)
Locks (gauge)
Process Count (graph)
Cache Efficiency (graph) (= 100*(LogicalReads/(LogicalReads + Physical Reads)) )
Licenses Used (gauge)
Global Global Refs
Global Sets 1
Global Kills 2
Global Reads
Blocks Allocated 2
Locks
Successful Locks
Failed Locks
Job InGlobal
WD QueSize
Global AvailBufs
Que Gaccess
Que GaccUpd
Que GBFAny
Que GBFSpec
Journal Entries
Jrn FileSize
Jrn EndOffset
Tot Global Bufs
GThrottle Cur
GThrottle Max
GThrottle Cnt
Routine Routine Lines 3
Routine Loads
Routine Fetches
Disk Activity Physical Directory Reads
Physical U-Ptr Reads
Physical B-Ptr Reads
Physical Data Reads
Physical Routine Reads
Physical Map Reads
Physical Other Reads
Physical Directory Writes
Physical U-Ptr Writes
Physical B-Ptr Writes
Physical Data Writes
Physical Routine Writes
Physical Map Writes
Physical Other Writes
Logical Directory Reads
Logical U-Ptr Reads
Logical B-Ptr Reads
Logical Data Reads
Logical Routine Reads
Logical Map Reads
Logical Other Reads
Network Net Global Refs
Net Global Sets
Net Global Kills 2
Net Global Reads
Net Requests Sent 2
Net Cache Hits
Net Cache Misses
Net Locks 2
Net Retransmits 2
Net Buffer
Net GblJobs
Other Terminal Reads 2
Terminal Writes 2
Terminal Read Char 2
Terminal Write Char 2
Sequential Read 2
Sequential Write 2
When using the default InterSystems IRIS standard counters (“light” version), the following notes are applicable:
1 Global Sets is a combination of Global Sets and Global Kills.
2 Counter is not available; therefore, this value is 0.
3 Routine Lines reflects the total commands executed.