Detailed Description

The pipeline module can generate and update monitoring information which is published to the Caplin Management Console or any other application that can interrogate a JMX mbean server.

Key Concepts:

Properties are individual name/value pairs.
Templates are collections of properties.

The monitoring API supports the following types:

Always on properties (which are always emitted by the application)
Request properties (which are generated on demand by the application)

Properties can consist of the following datatypes:

Strings
Integers
Floating point numbers
Booleans
Timestamps (seconds since 1 Jan 1970)
Arrays of the above datatypes

Defining the template

Monitoring and management items are grouped into templates consisting of information relating to a common object type, e.g. cache objects are associated with one type of template, datasource peers are associated with another.

A template declaration is begun with a call to monitoring.startTemplate(). The following example defines a template with a single string property names "status":

   monitoring.startTemplate("exampleinfo","Example monitoring information");
   monitoring.addProperty("exampleinfo","status","An example string property", monitoring.STRING);
   monitoring.endTemplate("exampleinfo");

Creating Template Instances (groups)

A template definition needs to be instantiated and a monitorable group created for each item that is required to be monitored. For example, if an application wishes to provide monitorable information for a the objects that it is publishing, then it needs to call monitoring.createGroup() for each individual object.

The following example will instantiate the template "exampleinfo" with the key "OBJECT1", this will be visible in a JMX explorer with the following path: transformer.exampleinfo.OBJECT1

monitoring.createGroup("exampleinfo", "OBJECT1", "Monitorable information about OBJECT1");

Deleting Groups

Groups should be deleted when no longer required, the function monitoring.deleteGroup() is provided for this purpose.

monitoring.deleteGroup("exampleinfo", "OBJECT1");

Populating values

Initial values and subsequent updates should be published to the monitoring system using either the ds_monitor_update group of functions, or alternatively using the ds_monitor_new group of functions and the ds_monitor_update() function.

The following example will publish the value "OK" to the status property:

monitoring.updateProperty("exampleinfo", "OBJECT1", "status", "OK");

Functions
	monitoring.startTemplate (var templateName, var description)
	Start the definition of a template. More...

	monitoring.endTemplate (var templateName)
	End the definition of a template. More...

	monitoring.addProperty (var templateName, var propertyName, var description, var type)
	Add a property to a template definition. More...

	monitoring.addActiveProperty (var templateName, var propertyName, var description, var type, var functionName)
	Add an active property to a template definition. More...

	monitoring.createGroup (var templateName, var groupName, var description, var shortDescription)
	Create a new monitoring group. More...

	monitoring.deleteGroup (var templateName, var groupName)
	Delete a group from the monitoring system. More...

	monitoring.updateProperty (var templateName, var groupName, var propertyName, var value)
	Update a monitoring property. More...

Variables
	monitoring.STRING
	Defines the string property type.

	monitoring.TIMESTAMP
	Defines the timestamp property type. More...

	monitoring.FLOAT
	Defines the floating point property type.

	monitoring.INT
	Defines the signed integer property type.

	monitoring.UINT
	Defines the unsigned integer property type.

	monitoring.ARRAY
	Defines the array property type. More...

Function Documentation

monitoring.addActiveProperty	(	var	templateName,
		var	propertyName,
		var	description,
		var	type,
		var	functionName
	)

Add an active property to a template definition.

Parameters

templateName	- The name of the template to add the property to
propertyName	- The name of the property to add
description	- A description of the purpose of the property
type	- Type of the property (eg monitoring.STRING)
functionName	- Name of the method that can supply the data

An active property is of use should the property value be an array, computationally expensive to update or otherwise undesirable to update antly.

monitoring.addProperty	(	var	templateName,
		var	propertyName,
		var	description,
		var	type
	)

Add a property to a template definition.

Parameters

templateName	- The name of the template to add the property to
propertyName	- The name of the property to add
description	- A description of the purpose of the property
type	- Type of the property (eg monitoring.STRING)

monitoring.createGroup	(	var	templateName,
		var	groupName,
		var	description,
		var	shortDescription
	)

Create a new monitoring group.

Parameters

templateName	- The name of the template to be used for this group
groupName	- The name of the group
description	- A long description for this group
shortDescription	- [optional] A shorter description for this group

The short description will be presented by the CMC in tree vide mode. The longer description is presented as "mouseover" text.

monitoring.deleteGroup	(	var	templateName,
		var	groupName
	)

Delete a group from the monitoring system.

Parameters

templateName	- The name of the template to be used for this group
groupName	- The name of the group to delete

monitoring.endTemplate ( var templateName )

End the definition of a template.

Parameters

templateName - Name of the template to end the definition for

This method should be called when the definition of the template has finished and all required properties have been added.

monitoring.startTemplate	(	var	templateName,
		var	description
	)

Start the definition of a template.

Parameters

templateName	- Name of the template to start definition of
description	- A generic description of the template

Note: It is not possible to redefine a template, however no checks are performed to ensure that this cannot happen

monitoring.updateProperty	(	var	templateName,
		var	groupName,
		var	propertyName,
		var	value
	)

Update a monitoring property.

Parameters

templateName	- Template name of the property to update
groupName	- Name of the group
propertyName	- Name of the property
value	- Value of the property

The supplied value will be automatically converted to the correct datatype, should the conversion fail then the execution of the pipeline script will be aborted - as is usual when any parameter is in error.

The following example demonstrates how to update a single property:

monitoring.updateProperty("exampleinfo", "OBJECT1", "status", "OK");

The following example demonstrates how to update a string array:

monitoring.updateProperty(templatename, group, propertyname, [ 'A', 'B', 'C', 'D', 'E' ]);

Variable Documentation

monitoring.ARRAY

Defines the array property type.

This type can be added to a fundamental property type to turn the the property into an array.

monitoring.TIMESTAMP

Defines the timestamp property type.

A timestamp measures the time in seconds since 1 Jan 1970.

Detailed Description

Functions

Variables

Function Documentation

Variable Documentation