Transformer SDK For C  6.2.11.309924
Monitoring API

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:

The monitoring API supports the following types:

Properties can consist of the following 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:

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:

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
templatenameThe templatename of the property being requested
keyThe primarykey of the property being requested
propertynameThe 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
credentialsUser 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
templatenameThe templatename of the method being called
keyThe primarykey of the method being called
propertynameThe propertyname of the method being requested
argcNumber of arguments
argvArray of arguments
Returns
ds_monitor_t A populated ds_monitor_t object

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


Generated on Sat Aug 26 2017 12:36:32 for Transformer SDK For C