Data Structures
struct	ds_arguments_t
	Structure defining the arguments for Monitoring methods. More...

struct	ds_array_t
	The container object for monitoring array types. More...

struct	ds_monauth_t
	Monitoring credentials object. More...

struct	ds_monitor_t
	The container object for all monitoring values. More...

Macros
#define	TYPE_ACTIVE 64
	Indicates whether the datatype is "active". More...

#define	TYPE_ACTIVE2 128
	Indicates whether the active type isn't a callback. More...

#define	TYPE_ARRAY 32
	Indicates whether the datatype is an array. More...

#define	TYPE_BINARY 1
	Binary property type. More...

#define	TYPE_BOOLEAN 11
	Boolean property type. More...

#define	TYPE_DOUBLE 9
	Double property type. More...

#define	TYPE_HIERARCHY 1024
	Indicates whether this data forms part of a heirarchy. More...

#define	TYPE_KEY 512
	Indicates whether this datatype forms part of the primary key. More...

#define	TYPE_LLONG 7
	Long long property type. More...

#define	TYPE_LONG 5
	Long property type. More...

#define	TYPE_METHOD 256
	Indicates whether this datatype is a method. More...

#define	TYPE_NONE 0
	A place marker. More...

#define	TYPE_OPTIONAL 2048

#define	TYPE_PRIMITIVE_MASK 31
	Mask to isolate the primitive data type. More...

#define	TYPE_RELATION 20
	Indicates that the property is a relation. More...

#define	TYPE_SHORT 3
	Short property type. More...

#define	TYPE_STRING 2
	String property type. More...

#define	TYPE_TIMESTAMP 10
	Timestamp property type. More...

#define	TYPE_ULLONG 8
	Unsigned long long property type. More...

#define	TYPE_ULONG 6
	Unsigned long property type. More...

#define	TYPE_USHORT 4
	Unsigned short property type. More...

Typedefs
typedef ds_monitor_t (	ds_monitor_active_cb) (char templatename, char key, char *propertyname)
	Definition of the function type used for active request callbacks. More...

typedef int(*	ds_monitor_authenticator_t) (ds_monauth_t *credentials)
	Definition of the function type used for monitoring authentication callback. More...

typedef ds_monitor_t (	ds_monitor_method_cb) (char templatename, char key, char property, int argc, char argv[])
	Definition of the function type used for method calls. More...

Detailed Description

DSDK provides an abstracted monitoring API in order for applications to write to a single API without having to concern themselves with how the information is being used.

Key Concepts:

Properties are individual name/value pairs.
Templates are collections of properties.
Links provide a way of navigating between templates.

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)
Methods (which permit an operation to be performed)
Relations (which link to separate templates together)
Subscriptions (which construct a link between a template and a singleton template).

Properties can consist of the following datatypes:

Strings
Short integers (signed and unsigned)
Long integers (signed and unsigned)
Long long integers (signed and unsigned)
Floating point (doubles)
Booleans
Timestamps (milliseconds since 1 Jan 1970)
Arrays of the above datatypes

Setting the server type

Each DataSource component exposes a property on a well-defined name and containing well-defined property names that provide hints to any monitoring application what monitoring data and management features the application provides. These values can be controlled by the DataSource application by calling the ds_monitor_add_server_type() function.

The Caplin JMX monitoring console uses the values set by this function to load the appropriate display-templates for the application that it is connected to.

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 begin with a call to ds_monitor_new_template(), items are added with ds_monitor_add_template_member() and a template declaration is ended with ds_monitor_end_template(). Ending the template definition will push the template definition to any monitoring plugin that has been loaded.

ds_monitor_start_template("datasrcname.object","Information about published objects");
ds_monitor_add_template_member("datasrcname.object","name","Name of the object",TYPE_STRING,NULL,NULL);
ds_monitor_add_template_member("datasrcname.object","last-update","Time of last update",TYPE_TIMESTAMP,NULL,NULL);
ds_monitor_end_template("datasrcname.object");

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 ds_monitor_create_group() for each individual object.

ds_monitor_create_group("datasrcname.object","/OBJECT1","Object info", "Monitorable information about /OBJECT1");

ds_monitor_create_group("datasrcname.object","/OBJECT2","Object info", "Monitorable information about /OBJECT2");

Deleting Groups

Groups should be deleted when no longer required, the function ds_monitor_delete_group() is provided for this purpose. All links should be removed prior to the deleting the group.

ds_monitor_delete_group("datasrcname.object","/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.

ds_monitor_update_timestamp("datasrcname.object","/OBJECT1", "last-update", (unsigned long long)time(NULL) * 1000);

or:

ds_monitor_t *mon;
mon = ds_monitor_new_timestamp("datasrcname.object","/OBJECT1", "last-update", (unsigned long long)time(NULL) * 1000);
ds_monitor_update("datasrcname.object","/OBJECT1", "last-update",mon);

Responding to requests for data

Method execution

The monitoring subsystem of DSDK permits management tools to affect the state of the DataSource, for example in the Caplin platform, methods are used to expose the following actions:

Force logfiles to wrap
Set the status of peer connections
Eject users from the Liberator
Cancel object subscriptions

Methods can take any number of arguments and return any type of data as a result.

Defining a method uses the ds_monitor_add_template_member() function. In order to indicate that a method is being added, the type type is or'd with TYPE_METHOD:

ds_monitor_add_template_member("datasrcname.object", "status", "Method to set object status",

TYPE_STRING|TYPE_METHOD, method_args, (void *) object_mon_status_cb);

The types of the arguments are defined using an array of ds_arguments_t. This array should be 0/NULL terminated as below:

static ds_arguments_t  method_args[] = {
    { TYPE_BOOL,  "status", "Object status (0 = stale)" },
    { TYPE_STRING|TYPE_OPTIONAL, "Status message", "Status message" },
    { 0, NULL, NULL }
};

Arguments can be specified as being optional in which case they do not need to be supplied by monitoring application. All arguments after the first optional argument should be marked as being optional.

Parameters are delivered the the DataSource application in the form of an array of strings. This permits implementation details to be shared between UDP events and management methods.

ds_monitor_t *object_mon_status_cb(char *template, char *key, char *methodname, int argc, argv[])
{
    /* argv[0] = methodname
     * argv[1] = object status
     * argv[2] = object status text
     */
}

Links

DSDK supports two sorts of links between objects, relations that bind templates together and subscriptions that bind templates together and implement a virtual group.

Relations

Relations are defined using the ds_monitor_add_template_relation() function. The multiplicity at each end can be set to either 0 (single) or 1 (many). For example a one to many relationship might be used to link all published objects to a single group containing statistical information about the objects the application is publishing (eg updates per seconds).

Relationships can be updated or removed using the ds_monitor_add_relation() and ds_monitor_del_relation() functions.

Subscriptions

Subscriptions are of use when the creation of an individual group for an item would result in a large number of groups being created. For example, subscriptions are used by the Liberator to obtain details of what objects a client is subscribed to. If we consider the case where a Liberator has a 1,000 clients each subscribing to 1,000 objects, if we were to create a group for each subscription then there would be 1,000,000 groups within the monitoring system which clearly isn't scalable.

Subscriptions are defined in the template using the ds_monitor_add_subscription() function, contents may be updated and removed using the ds_monitor_add_subscription() and ds_monitor_del_subscription() functions.

Macro Definition Documentation

#define TYPE_ACTIVE 64

Indicates whether the datatype is "active".

#define TYPE_ACTIVE2 128

Indicates whether the active type isn't a callback.

There are two forms of active monitoring types:

A function callback is supplied that provides that data
An address is supplied where the data can be obtained

If TYPE_ACTIVE2 then the same value is supplied for all groups of the template type

#define TYPE_ARRAY 32

Indicates whether the datatype is an array.

#define TYPE_BINARY 1

Binary property type.

#define TYPE_BOOLEAN 11

Boolean property type.

The Boolean value has the value 0 or 1

#define TYPE_DOUBLE 9

Double property type.

#define TYPE_HIERARCHY 1024

Indicates whether this data forms part of a heirarchy.

#define TYPE_KEY 512

Indicates whether this datatype forms part of the primary key.

#define TYPE_LLONG 7

Long long property type.

#define TYPE_LONG 5

Long property type.

#define TYPE_METHOD 256

Indicates whether this datatype is a method.

#define TYPE_NONE 0

A place marker.

#define TYPE_OPTIONAL 2048

For the type of the argument within a ds_arguments_t, this value can be or'd to indicate to the monitoring system that this argument is optional. All arguments after this particular argument should naturally be optional.

#define TYPE_PRIMITIVE_MASK 31

Mask to isolate the primitive data type.

#define TYPE_RELATION 20

Indicates that the property is a relation.

#define TYPE_SHORT 3

Short property type.

#define TYPE_STRING 2

String property type.

#define TYPE_TIMESTAMP 10

Timestamp property type.

The timestamp should be supplied in milliseconds

#define TYPE_ULLONG 8

Unsigned long long property type.

#define TYPE_ULONG 6

Unsigned long property type.

#define TYPE_USHORT 4

Unsigned short property type.

Typedef Documentation

typedef ds_monitor_t*(* ds_monitor_active_cb) (char *templatename, char *key, char *propertyname)

Definition of the function type used for active request callbacks.

Parameters

templatename	The templatename of the property being requested
key	The primarykey of the property being requested
propertyname	The propertyname being requested

Returns: ds_monitor_t A populated ds_monitor_t object

typedef int(* ds_monitor_authenticator_t) (ds_monauth_t *credentials)

Definition of the function type used for monitoring authentication callback.

Parameters

credentials User credentials to be authenticated

Return values

0	- User is not permitted to connect
1	- User is permitted to connect

See also: ds_monitor_set_auth()

typedef ds_monitor_t*(* ds_monitor_method_cb) (char *templatename, char *key, char *property, int argc, char *argv[])

Definition of the function type used for method calls.

Parameters

templatename	The templatename of the method being called
key	The primarykey of the method being called
propertyname	The propertyname of the method being requested
argc	Number of arguments
argv	Array of arguments

Returns: ds_monitor_t A populated ds_monitor_t object

argv[0] contains the propertyname this method is being called for

Data Structures

Macros

Typedefs

Detailed Description

Macro Definition Documentation

Typedef Documentation