Monitoring Caché Using Web Services

Overview of Caché Support for WS-Monitoring

Following the WS-Management specificationOpens in a new tab, 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:

• The Caché Monitoring Web Service (SYS.WSMon.ServiceOpens in a new tab) that provides methods that return information about a Caché instance.

• A Caché web client (SYS.WSMon.ClientOpens in a new tab) that can invoke methods in this Monitoring Web Service or in the Monitoring Web Service of another Caché instance.

  Instead of using this web client, you can create your own web client, possibly using third-party technology.

• Several XML-enabled classes that this web service and client use to represent monitoring information.

  These classes include SYS.WSMon.wsEventOpens in a new tab, which can represent events.

• A sample event sink web service (SYS.WSMon.EventSinkOpens in a new tab) that can receive and process events. Via a SOAP call, you can subscribe to this sample event sink service so that it will receive events from any Monitoring Web Service.

  Instead of using this sample, you can create your own, possibly using third-party technology.

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 Atelier 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:

• wxf:Get

• wsen:Enumerate

• wsen:Pull

• wsen:Release

• wse:Subscribe

• wse:Renew

• wse:Unsubscribe

For more information, see the WS-Management specification (https://www.dmtf.org/standards/published_documents/DSP0226_1.1.pdf)Opens in a new tab.

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.ServiceOpens in a new tab class provides the following web methods:

EnumBuffer()

method EnumBuffer() as %XML.DataSet

Returns an instance of %XML.DataSetOpens in a new tab that enumerates the statistics for all buffer sizes. For this instance, the dataset uses the Sample() class query of the SYS.Stats.BufferOpens in a new tab class.

For information on working with %XML.DataSetOpens in a new tab, see the chapter “Using Datasets in SOAP Messages” in Creating Web Services and Web Clients in Caché or see the class reference for %XML.DataSetOpens in a new tab.

Also see the class reference for SYS.Stats.BufferOpens in a new tab.

EnumDatabase()

method EnumDatabase() as %XML.DataSet

Returns an instance of %XML.DataSetOpens in a new tab that enumerates all databases for this instance. For this instance, the dataset uses the List() class query of the SYS.WSMon.wsDatabaseOpens in a new tab class.

See the comments for EnumBuffer() and see the class reference for SYS.WSMon.wsDatabaseOpens in a new tab.

EnumResource()

method EnumResource() as %XML.DataSet

Returns an instance of %XML.DataSetOpens in a new tab that enumerates statistics for all system resource seizes. For this instance, the dataset uses the Sample() class query of the SYS.Stats.ResourceOpens in a new tab class.

See the comments for EnumBuffer() and see the class reference for SYS.Stats.ResourceOpens in a new tab.

EnumWriteDaemon()

method EnumWriteDaemon() as %XML.DataSet

Returns an instance of %XML.DataSetOpens in a new tab that enumerates statistics for all write daemons. For this instance, the dataset uses the Sample() class query of the SYS.Stats.WriteDaemonOpens in a new tab class.

See the comments for EnumBuffer() and see the class reference for SYS.Stats.WriteDaemonOpens in a new tab.

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.EventSinkOpens in a new tab web service, which is provided as an example. If you create your own web service, it must follow the WSDL of the SYS.WSMon.EventSinkOpens in a new tab web service.

For location, specify the URL needed to invoke the EventSink() method of the web service. For SYS.WSMon.EventSinkOpens in a new tab, 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.wsEventOpens in a new tab.

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.DiskOpens in a new tab that contains metrics of disk usage for globals for this instance.

See the class reference for SYS.Stats.DiskOpens in a new tab.

GetECPAppSvr()

method GetECPAppSvr() as SYS.Stats.ECPAppSvr

Returns an instance of SYS.Stats.ECPAppSvrOpens in a new tab that contains ECP application server metrics for this instance.

See the class reference for SYS.Stats.ECPAppSvrOpens in a new tab.

GetECPDataSvr()

method GetECPDataSvr() as SYS.Stats.ECPDataSvr

Returns an instance of SYS.Stats.ECPDataSvrOpens in a new tab that contains ECP database server metrics for this instance.

See the class reference for SYS.Stats.ECPDataSvrOpens in a new tab.

GetGlobal()

method GetGlobal() as SYS.Stats.Global

Returns an instance of SYS.Stats.GlobalOpens in a new tab that contains global metrics for this instance.

See the class reference for SYS.Stats.GlobalOpens in a new tab.

GetRoutine()

method GetRoutine() as SYS.Stats.Routine

Returns an instance of SYS.Stats.RoutineOpens in a new tab that contains routine metrics for this instance.

See the class reference for SYS.Stats.RoutineOpens in a new tab.

GetSystem()

method GetSystem() as SYS.WSMon.wsSystem

Returns an instance of SYS.WSMon.wsSystemOpens in a new tab that contains system information about the Caché instance.

See the class reference for SYS.WSMon.wsSystemOpens in a new tab.

Monitoring Web Client

The SYS.WSMon.ClientOpens in a new tab 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.

   See Creating Web Services and Web Clients in Caché.

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>set $namespace = %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.

Processing Events

Caché provides a sample web service (SYS.WSMon.EventSinkOpens in a new tab) 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.EventSinkOpens in a new tab 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>set $namespace = %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 Atelier 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.