Skip to main content
Previous sectionNext section

Monitoring InterSystems IRIS Using Web Services

This appendix introduces and briefly describes how to use InterSystems IRIS® data platform support for the WS-Management specification, which enables you to remotely monitor an InterSystems IRIS instance via SOAP.

Overview of InterSystems IRIS Support for WS-Monitoring

Following the WS-Management specificationOpens in a new window, 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 window) that provides methods that return information about an InterSystems IRIS instance.

  • An InterSystems IRIS web service client (SYS.WSMon.ClientOpens in a new window) 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 window, which can represent events.

  • A sample event sink web service (SYS.WSMon.EventSinkOpens in a new window) 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 window.

URL for the Monitoring Web Service

For a given InterSystems IRIS instance, the Log Monitoring Web Service is available at the following URL:

http://server:port/csp/sys/SYS.WSMon.Service.cls
Copy code to clipboard

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

http://localhost:52773/csp/sys/SYS.WSMon.Service.cls
Copy code to clipboard

Similarly, the WSDL for this web service is available at the following URL:

http://server:port/csp/sys/SYS.WSMon.Service.cls?WSDL=1
Copy code to clipboard

Web Methods of the Monitoring Web Service

The SYS.WSMon.ServiceOpens in a new window class provides the following web methods:

EnumBuffer()
method EnumBuffer() as %XML.DataSet
Copy code to clipboard

Returns an instance of %XML.DataSetOpens in a new window 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 window class.

For information on working with %XML.DataSetOpens in a new window, 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 window.

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

EnumDatabase()
method EnumDatabase() as %XML.DataSet
Copy code to clipboard

Returns an instance of %XML.DataSetOpens in a new window 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 window class.

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

EnumResource()
method EnumResource() as %XML.DataSet
Copy code to clipboard

Returns an instance of %XML.DataSetOpens in a new window 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 window class.

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

EnumWriteDaemon()
method EnumWriteDaemon() as %XML.DataSet
Copy code to clipboard

Returns an instance of %XML.DataSetOpens in a new window 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 window class.

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

EventCancel()
method EventCancel(id) as %Integer
Copy code to clipboard

Cancels the subscription for a given web service; see EventSubscribe().

EventSubscribe()
method EventSubscribe(location) as %String
Copy code to clipboard

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 window 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 window web service.

For location, specify the URL needed to invoke the EventSink() method of the web service. For SYS.WSMon.EventSinkOpens in a new window, you might specify location as the following:

http://server:port/csp/sys/SYS.WSMon.EventSink.cls
Copy code to clipboard

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 window.

This method returns an ID that you can use to cancel the subscription; see EventCancel().

GetDisk()
method GetDisk() as SYS.Stats.Disk
Copy code to clipboard

Returns an instance of SYS.Stats.DiskOpens in a new window that contains metrics of disk usage for globals for this instance.

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

GetECPAppSvr()
method GetECPAppSvr() as SYS.Stats.ECPAppSvr
Copy code to clipboard

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

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

GetECPDataSvr()
method GetECPDataSvr() as SYS.Stats.ECPDataSvr
Copy code to clipboard

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

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

GetGlobal()
method GetGlobal() as SYS.Stats.Global
Copy code to clipboard

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

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

GetRoutine()
method GetRoutine() as SYS.Stats.Routine
Copy code to clipboard

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

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

GetSystem()
method GetSystem() as SYS.WSMon.wsSystem
Copy code to clipboard

Returns an instance of SYS.WSMon.wsSystemOpens in a new window that contains system information about the InterSystems IRIS instance.

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

Monitoring Web Client

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

Parameter LOCATION = "http://server:port/csp/sys/SYS.WSMon.Service.cls" 
Copy code to clipboard

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: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>
Copy code to clipboard

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

InterSystems IRIS provides a sample web service (SYS.WSMon.EventSinkOpens in a new window) 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 window 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:

http://server:port/csp/sys/SYS.WSMon.EventSink.cls
Copy code to clipboard

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
Copy code to clipboard

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:52773/csp/sys/SYS.WSMon.EventSink.cls"
 
%SYS>set subscriptionid=client.EventSubscribe(eventsinklocation)
 
%SYS>write subscriptionid
CacheEventSubscription_2
Copy code to clipboard

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
Copy code to clipboard

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.

FeedbackOpens in a new window