Caché Monitoring Guide
Monitoring Caché Using Web Services
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This appendix introduces and briefly describes how to use Caché support for the WS-Management specification, which enables you to remotely monitor a Caché instance via SOAP.

Overview of Caché Support for WS-Monitoring
Following the WS-Management specification, the SYS.WSMon package provides a web service that you can use to remotely monitor a Caché instance. It is functionally similar to the SNMP interface (see the Monitoring Caché Using SNMP appendix of this guide) and WMI interface (see the Monitoring Caché Using WMI appendix of this guide), but uses the built-in Caché web services support.
The support for WS-Management includes the following elements:
These classes are available only in the %SYS namespace.
For basic monitoring, you can use the Caché Monitoring Web Service with a web client in another instance as follows:
In more advanced cases, the web client subscribes an event sink service, possibly running on another Caché instance. For example:
Your event sink web service can perform any processing needed by the business.
Note that Studio provides the SOAP Wizard, which can generate web services and web clients from a WSDL. For details on using this wizard, see Creating Web Services and Web Clients in Caché. (Many third-party technologies also provide similar wizards.)
Support Details
InterSystems supports the following parts of the WS-Management specification:
For more information, see the WS-Management specification (http://www.dmtf.org/standards/published_documents/DSP0226_1.1.pdf).
URL for the Monitoring Web Service
For a given Caché instance, the Caché Monitoring Web Service is available at the following URL:
http://server:port/csp/sys/SYS.WSMon.Service.cls
Where server is the server on which Caché is running and port is the port that the Caché web server uses. For example:
http://localhost:57772/csp/sys/SYS.WSMon.Service.cls
Similarly, the WSDL for this web service is available at the following URL:
http://server:port/csp/sys/SYS.WSMon.Service.cls?WSDL=1
Web Methods of the Monitoring Web Service
The SYS.WSMon.Service class provides the following web methods:
EnumBuffer()
method EnumBuffer() as %XML.DataSet
Returns an instance of %XML.DataSet that enumerates the statistics for all buffer sizes. For this instance, the dataset uses the Sample() class query of the SYS.Stats.Buffer class.
For information on working with %XML.DataSet, see the chapter Using Datasets in SOAP Messages in Creating Web Services and Web Clients in Caché or see the class reference for %XML.DataSet.
Also see the class reference for SYS.Stats.Buffer.
EnumDatabase()
method EnumDatabase() as %XML.DataSet
Returns an instance of %XML.DataSet that enumerates all databases for this instance. For this instance, the dataset uses the List() class query of the SYS.WSMon.wsDatabase class.
See the comments for EnumBuffer() and see the class reference for SYS.WSMon.wsDatabase.
EnumResource()
method EnumResource() as %XML.DataSet
Returns an instance of %XML.DataSet that enumerates statistics for all system resource seizes. For this instance, the dataset uses the Sample() class query of the SYS.Stats.Resource class.
See the comments for EnumBuffer() and see the class reference for SYS.Stats.Resource.
EnumWriteDaemon()
method EnumWriteDaemon() as %XML.DataSet
Returns an instance of %XML.DataSet that enumerates statistics for all write daemons. For this instance, the dataset uses the Sample() class query of the SYS.Stats.WriteDaemon class.
See the comments for EnumBuffer() and see the class reference for SYS.Stats.WriteDaemon.
EventCancel()
method EventCancel(id) as %Integer
Cancels the subscription for a given web service; see EventSubscribe().
EventSubscribe()
method EventSubscribe(location) as %String
Subscribes the given web service to receive information about events in this Caché instance. This can be your own web service or can be the SYS.WSMon.EventSink web service, which is provided as an example. If you create your own web service, it must follow the WSDL of the SYS.WSMon.EventSink web service.
For location, specify the URL needed to invoke the EventSink() method of the web service. For SYS.WSMon.EventSink, you might specify location as the following:
http://server:port/csp/sys/SYS.WSMon.EventSink.cls
Where server is the server on which Caché is running, and port is the port that Caché uses.
For each event, Caché will attempt to call EventSink() method of the given web service, sending an instance of SYS.WSMon.wsEvent.
This method returns an ID that you can use to cancel the subscription; see EventCancel().
GetDisk()
method GetDisk() as SYS.Stats.Disk
Returns an instance of SYS.Stats.Disk that contains metrics of disk usage for globals for this instance.
See the class reference for SYS.Stats.Disk.
GetECPAppSvr()
method GetECPAppSvr() as SYS.Stats.ECPAppSvr
Returns an instance of SYS.Stats.ECPAppSvr that contains ECP application server metrics for this instance.
See the class reference for SYS.Stats.ECPAppSvr.
GetECPDataSvr()
method GetECPDataSvr() as SYS.Stats.ECPDataSvr
Returns an instance of SYS.Stats.ECPDataSvr that contains ECP database server metrics for this instance.
See the class reference for SYS.Stats.ECPDataSvr.
GetGlobal()
method GetGlobal() as SYS.Stats.Global
Returns an instance of SYS.Stats.Global that contains global metrics for this instance.
See the class reference for SYS.Stats.Global.
GetRoutine()
method GetRoutine() as SYS.Stats.Routine
Returns an instance of SYS.Stats.Routine that contains routine metrics for this instance.
See the class reference for SYS.Stats.Routine.
GetSystem()
method GetSystem() as SYS.WSMon.wsSystem
Returns an instance of SYS.WSMon.wsSystem that contains system information about the Caché instance.
See the class reference for SYS.WSMon.wsSystem.
Monitoring Web Client
The SYS.WSMon.Client class and related classes are a Caché web client that can invoke methods of SYS.WSMon.Server web service in the same Caché instance or another Caché instance.
This web client class uses the following LOCATION parameter:
Parameter LOCATION = "http://server:port/csp/sys/SYS.WSMon.Service.cls" 
Where server is the server on which Caché is running and port is the port that the Caché web server uses.
Use this web client in the same way that you use other Caché web clients:
  1. Create an instance of the web client class.
  2. Set its Location property if needed.
    This is necessary if the SYS.WSMon.Server web service that you want to use is on a different machine than the client, or if it uses a port other than 57772.
  3. Set other properties if needed.
  4. Invoke a web method.
  5. Examine the value returned by the web method.
    The details depend on the web method you invoke; see the section Web Methods of the Monitoring Web Service and see the class reference for the return types.
The following shows an example Terminal session:
SAMPLES>zn "%sys"
 
%SYS>Set client=##class(SYS.WSMon.Client).%New()
 
%SYS>Set client.Location="http://localhost:57799/csp/sys/SYS.WSMon.Service.cls"
 
%SYS>Set myroutinestats=client.GetRoutine()
 
%SYS>Write myroutinestats.RtnCallsLocal
19411581
%SYS>Write myroutinestats.RtnCallsRemote
0
%SYS>Write myroutinestats.RtnCommands
432764817
%SYS>
More typically, you create and use the client programmatically, perhaps to retrieve data for display in a user interface.
Note:
Remember that the SYS.WSMon package is available only in %SYS namespace, which means that you must be in that namespace to perform the steps described here.
Processing Events
Caché provides a sample web service (SYS.WSMon.EventSink) that can receive and process events sent by any Caché Monitoring Web Service. You can use this web service or create and use your own.
Using the Sample Event Sink Web Service
SYS.WSMon.EventSink is a sample Caché web service that can receive and process events.
For a given Caché instance, the Caché Monitoring Web Service is available at the following URL:
http://server:port/csp/sys/SYS.WSMon.EventSink.cls
Where server is the server on which Caché is running and port is the port that the Caché web server uses.
This web service has one method:
CacheEventSink()
Method CacheEventSink(event As SYS.WSMon.wsEvent) As %Integer
On Windows platforms, this sample method displays a popup window when an event occurs; for other platforms, it adds an entry to ^SYS("MONITOR","WSMON","EVENT_RECEIVED",$h).
This method always returns 1.
To subscribe this sample service so that it will receive events from the Monitoring Web Service, do the following in the Terminal:
SER>zn "%sys"
 
%SYS>Set client=##class(SYS.WSMon.Client).%New()
 
%SYS>Set eventsinklocation="http://localhost:57772/csp/sys/SYS.WSMon.EventSink.cls"
 
%SYS>Set subscriptionid=client.EventSubscribe(eventsinklocation)
 
%SYS>Write subscriptionid
CacheEventSubscription_2
Here eventsinklocation is the URL for the event sink web service that will process events.
Creating Your Own Event Sink Web Service
To create your own event sink web service, use the SOAP Wizard in Studio to generate a web service from the following WSDL:
http://server:port/csp/sys/SYS.WSMon.EventSink.cls?WSDL=1
Where server is the server on which Caché is running and port is the port that the Caché web server uses.
For details on using this wizard, see Creating Web Services and Web Clients in Caché.
Then modify the CacheEventSink() method in the generated web service to include your custom logic.