Monitoring InterSystems IRIS Using Web Services

Overview of InterSystems IRIS 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 an InterSystems IRIS instance. It is functionally similar to the SNMP interface (see the “Monitoring InterSystems IRIS Using SNMP” appendix of this guide), but uses the built-in InterSystems IRIS web service services support.

The support for WS-Management includes the following elements:

• The Log Monitoring Web Service (SYS.WSMon.ServiceOpens in a new tab) that provides methods that return information about an InterSystems IRIS instance.

• An InterSystems IRIS web service 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 InterSystems IRIS 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 Log Monitoring Web Service with a web client in another instance. The image below shows a monitoring client requesting monitoring data from a target instance. The Log Monitoring Web Service on the target instance responds, sending the client monitoring data.

In more advanced cases, the web client subscribes an event sink service, possibly running on another InterSystems IRIS instance. For example, in the image below the monitoring client sends a request to the primary instance to subscribe a third instance. The primary instance’s Monitoring Web Service responds by sending subscription ID to the client, and thereafter sends events to the third instance. The third instance can process these events in a number of ways, such as to create custom reporting or alerting.

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. (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 InterSystems IRIS instance, the Log Monitoring Web Service is available at the following URL, using the <baseURL> for your instance:

http://<baseURL>/csp/sys/SYS.WSMon.Service.cls

For example:

http://localhost:8000/csp/sys/SYS.WSMon.Service.cls

Similarly, the WSDL for this web service is available at the following URL, again using the <baseURL> for your instance:

http://<baseURL>/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 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 InterSystems IRIS 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, using the <baseURL> for your instance. For SYS.WSMon.EventSinkOpens in a new tab, you might specify location as the following:

http://<baseURL>/csp/sys/SYS.WSMon.EventSink.cls

Where server is the server on which InterSystems IRIS is running, and port is the port that InterSystems IRIS uses.

For each event, InterSystems IRIS 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 InterSystems IRIS 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 an InterSystems IRIS web service client that can invoke methods of SYS.WSMon.Server web service in the same InterSystems IRIS instance or another InterSystems IRIS instance.

This web client class uses the following LOCATION parameter, using the <baseURL> for your instance:

Parameter LOCATION = "http://<baseURL>/csp/sys/SYS.WSMon.Service.cls" 

Where server is the server on which InterSystems IRIS is running and port is the port that the InterSystems IRIS web service server uses.

Use this web client in the same way that you use other InterSystems IRIS web service 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 52773.

3. Set other properties if needed.

   See Creating Web Services and Web Clients.

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:

USER>set $namespace = "%SYS"
 
%SYS>set client=##class(SYS.WSMon.Client).%New()
 
%SYS>set client.Location="http://localhost:8000/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

InterSystems IRIS provides a sample web service (SYS.WSMon.EventSinkOpens in a new tab) that can receive and process events sent by any Log 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 InterSystems IRIS web service service that can receive and process events.

For a given InterSystems IRIS instance, the Log Monitoring Web Service is available at the following URL, using the <baseURL> for your instance:

http://<baseURL>/csp/sys/SYS.WSMon.EventSink.cls

Where server is the server on which InterSystems IRIS is running and port is the port that the InterSystems IRIS web service 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:

USER>set $namespace = "%sys"
 
%SYS>set client=##class(SYS.WSMon.Client).%New()
 
%SYS>set eventsinklocation="http://localhost:8000/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, using the <baseURL> for your instance:

http://<baseURL>/csp/sys/SYS.WSMon.EventSink.cls?WSDL=1

Where server is the server on which InterSystems IRIS is running and port is the port that the InterSystems IRIS web service server uses.

For details on using this wizard, see Creating Web Services and Web Clients.

Then modify the CacheEventSink() method in the generated web service to include your custom logic.