Monitoring interface

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.template_start(). The following example defines a template with a single string property names "status":

   monitoring.template_start("exampleinfo","Example monitoring information")
   monitoring.template_add_property("exampleinfo","status","An example string property", monitoring.STRING)
   monitoring.template_end("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.group_create() 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.group_create("exampleinfo", "OBJECT1", "Monitorable information about OBJECT1");

Deleting Groups

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

   monitoring.group_delete("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.update("exampleinfo", "OBJECT1", "status", "OK");

Functions
	monitoring.template_start (var template_name, var description)
	Start the definition of a template. More...
	monitoring.template_end (var template_name)
	End the definition of a template. More...
	monitoring.template_add_property (var template_name, var property_name, var description, var type)
	Add a property to a template definition. More...
	monitoring.template_add_active_property (var template_name, var property_name, var description, var type, var function_name)
	Add an active property to a template definition. More...
	monitoring.group_create (var template_name, var group_name, var description, var short_description)
	Create a new monitoring group. More...
	monitoring.group_delete (var template_name, var group_name)
	Delete a group from the monitoring system. More...
	monitoring.update (var template_name, var group_name, var property_name, var value)
	Update a monitoring property. More...

Variables
const	monitoring.STRING
	Defines the string property type.
const	monitoring.TIMESTAMP
	Defines the timestamp property type. More...
const	monitoring.FLOAT
	Defines the floating point property type.
const	monitoring.INT
	Defines the signed integer property type.
const	monitoring.UINT
	Defines the unsigned integer property type.
const	monitoring.ARRAY
	Defines the array property type. More...

Function Documentation

monitoring.group_create	(	var	template_name,
		var	group_name,
		var	description,
		var	short_description
	)

Create a new monitoring group.

Parameters

template_name	- The name of the template to be used for this group
group_name	- The name of the group
description	- A long description for this group
short_description	- [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.group_delete	(	var	template_name,
		var	group_name
	)

Delete a group from the monitoring system.

Parameters

template_name	- The name of the template to be used for this group
group_name	- The name of the group to delete

monitoring.template_add_active_property	(	var	template_name,
		var	property_name,
		var	description,
		var	type,
		var	function_name
	)

Add an active property to a template definition.

Parameters

template_name	- The name of the template to add the property to
property_name	- The name of the property to add
description	- A description of the purpose of the property
type	- Type of the property (eg monitoring.STRING)
function_name	- 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 constantly.

monitoring.template_add_property	(	var	template_name,
		var	property_name,
		var	description,
		var	type
	)

Add a property to a template definition.

Parameters

template_name	- The name of the template to add the property to
property_name	- 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.template_end

(

var

template_name

)

End the definition of a template.

Parameters

template_name

- 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.template_start	(	var	template_name,
		var	description
	)

Start the definition of a template.

Parameters

template_name	- 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.update	(	var	template_name,
		var	group_name,
		var	property_name,
		var	value
	)

Update a monitoring property.

Parameters

template_name	- Template name of the property to update
group_name	- Name of the group
property_name	- 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.update("exampleinfo", "OBJECT1", "status", "OK");

The following example demonstrates how to update a string array:

    monitoring.update(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.