Monitoring Caché Using BMC PATROL
As of early 2015, InterSystems will stop enhancing the PATROL knowledge module files provided with Caché; in 2016, InterSystems will remove these PATROL knowledge files from supplied kits. However, BMC provides an SNMP interface for its PATROL product, allowing you to continue to use PATROL in conjunction with the Caché SNMP interface documented in the “Monitoring Caché Using SNMP” appendix of this guide. See http://blog.intersystems.com/compatibility/2015/01/ for more information.
This appendix describes the interface between Caché and BMC PATROL.
BMC PATROL is a tool for monitoring and managing various software systems. Caché supplies PATROL extensions so that you can monitor and collect information about Caché.
This interface allows users to monitor metrics of one or multiple Caché systems from the PATROL Console. The interface requires that the PATROL daemon is running on the Caché system to collect and output the metric values and that the Caché knowledge module files (*.km) are loaded into the PATROL Console to read and display these values.
This appendix provides information on the following topics:
Run the ^PATROL ObjectScript routine on each Caché 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 Caché manager’s directory install-dir\Mgr (where install-dir is the Caché 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 Caché:
Automatic PATROL Startup — You can set an option to automatically start the PATROL daemon at Caché startup using the Management Portal:
Navigate to the System > Configuration > Monitor Settings page of the Management Portal.
ClickYesin the Start Patrol at System Startup setting box.WhenYes, the connection to PATROL starts automatically whenever Caché starts up. The default isNo. When you edit this setting, the Caché end of the PATROL interface immediately stops and starts.
PATROL Arguments — From the same System > Configuration > Monitor Settings page of the Management Portal, you can also set the following PATROL settings:
Patrol Top Processes to Monitor — Number of processes displayed in the Process Status window on the PATROL console. This window shows the top processes as sorted by global or routine activity. The default number of processes is 20. A value of 0 tells the PATROL utility to stop calculating the top processes, potentially saving significant work on systems with many processes. The valid range is 1–10000 processes.
Patrol Display Mode — Controls how the monitoring data is displayed in the PATROL console. The default option isTotal. Options are as follows:
Totaldisplays the total counts since the collection was started.
Deltadisplays the count for the last collection period.
Ratedisplays a calculated count per second.
Patrol Collection Interval Seconds — Number of seconds between each time Caché collects data and makes it available to PATROL. The default is 30 seconds; the valid range is 1–900 seconds.
By default, PATROL uses standard Caché system counters to generate metrics (for more information see Caché 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:
where n is:
0— PATROL uses extended counters
1— PATROL uses standard counters (“light” version)
To see which version is currently specified, in the Terminal, enter the following command:
Caché provides entry points to the ^PATROL routine to start and stop PATROL.
To start PATROL:
The arguments are described in the following table:
|Argument||Description||Default||Management Portal Monitor Setting|
|display||Display mode. The literals
rateto indicate the type of numbers to output.
|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|
Sets the PATROL console to display the total statistic counts, since the collection started, for the top 20 processes; Caché 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:
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 Caché plug-in for PATROL consists of several knowledge modules to be loaded into the PATROL Console. These .km files are provided in the Caché Patrol directory, install-dir\Patrol.
Once these knowledge modules are loaded, the Console automatically attempts to discover Caché installations on all connected systems. The discovery process either searches the Registry on Windows platforms or parses the output from the ccontrol list command on UNIX®/Linux platforms. For each Caché installation it finds it checks to see if the patrol.dat file exists in the Caché manager's directory and if the time stamp within that file is current. Caché installations which are currently reporting Caché metrics for PATROL appear in the PATROL Console.
Included in the Patrol directory is the ISC_CACHE.kml file listing all of the Caché knowledge modules. Use the following procedure to load and activate the knowledge modules:
From the PATROL Console File menu, click Load KM.
Select the ISC_CACHE.kml file in the Caché Patrol directory, install-dir\Patrol.
The ISC_CACHE module should appear in the Desktop tab of the Console in a few seconds.
Right-click ISC_CACHE and choose Add Configuration from the KM Commands menu.
In the Add Configuration dialog box, enter an instance name and the Caché installation directory.
You may need to wait for, at most, 30 seconds (PATROL default sync period), before PATROL recognizes Caché statistics.
For more information you can consult the BMC Web site.
If any Caché installations are discovered on a system, then the main entry for Caché (the Caché class) appears under that system entry. Each Caché instance (each Caché configuration installed on that system) appears under the Caché class. Under each Caché instance are the general metric categories of Overview, Global, Routines, Disk Activity, Network, and Other.
- 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 Caché configuration allows the user to select Caché-specific commands, to either Remove Configuration or show a Process Status window.
Manually adding a configuration should not normally be necessary, since all Caché 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 Caché KMs may be output to the System Output window. Check these messages if you have questions about Caché installations that are not automatically discovered.
The list of metrics for Caché:
Caché PATROL Metrics
|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)|
|Process Count (graph)|
|Cache Efficiency (graph) (= 100*(LogicalReads/(LogicalReads + Physical Reads)) )|
|Licenses Used (gauge)|
|Global Sets 1|
|Global Kills 2|
|Blocks Allocated 2|
|Tot Global Bufs|
|Routine||Routine Lines 3|
|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|
|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 Caché 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.