XML-RPC Instrumentation API

Using the API

myManEnt.mySampler.createView

myManEnt.mySampler.myGroupmyView.addHeadline

myManEnt.mySampler(myType).createView

Introduction

The following sections provide concrete examples of how to construct custom views using the Geneos API in C++. The example view will show a set of dataviews for a particular component of a custom developed system and will look like this:

Although it is possible to write an API client without using any supporting libraries, it is easier to use an XML-RPC library. Here we will give examples of how to write a simple API client in C++ using the XmlRpc++ library.

The following are the implementation steps:

• Write API client in C++.
• Link with XML-RPC++ library.
• Create API plug-in using the Gateway setup.
• Run the API client.

Note: The XML-RPC C++ is written in 2003 and is compiled on gcc-3. It is recommended to use a compatible compiler with gcc and install the following packages, such as compat-gcc-34-3.4.6-46.fc28.x86_64.rpm and compat-gcc-34-c++-3.4.6-46.fc28.x86_64.rpm.

Writing a C++ Client

The XmlRpc++ library defines several classes that make it easy to call functions on an XML-RPC server. This step-by-step example shows how to use these classes and is followed by the complete working program and an explanation of how to get started.

XmlRpcClient c(server, port, "/xmlrpc");

This defines a client called c that will connect to server on port and use the URI /xmlrpc to handle the requests. Server should be a char* and port should be an int.

XmlRpcValue parameters;
XmlRpcValue result;

These define variables that can be used to pass parameters to and collect the result from a function call. All values are represented as XmlRpcValues. The [] operator has been overloaded to provide arrays of XmlRpcValues and structures of XmlRpcValues. Several cast operators have also been overloaded to provide easy conversions.

parameters[0] = "queues";
parameters[1] = "myGroup";

This defines the first parameter as the text string "queues" and the second parameter as "myGroup".

if (c.execute("myManEnt.mySampler.createView", parameters, result))
 std::cout << "Result: " << result << "\n";

The execute function takes three parameters. The first two define the remote function to call and the parameters to pass to the remote function. The function returns true if it was possible to execute the method remotely, false if there was a problem connecting to the remote host. If the execute function returns true then the third (result) parameter will be populated with the remote function's return value and this can then be output to the screen or processed as necessary.

The above code creates the queues view in the mySampler plug-in. It will be listed under the group heading "myGroup".

parameters[0] = "totalQueues";
if (c.execute("myManEnt.mySampler.myGroup-queues.addHeadline", parameters, result))
 if (c.isFault())
 if ((int)result["faultCode"] == NO_SUCH_SAMPLER)
  std::cout << "NO_SUCH_SAMPLER\n";

Even if the remote call executes successfully, result may in fact be an error. This can be checked for by calling the isFault() function on the XmlRpcClient object. If isFault() returns true then result will be a structure with a faultCode and a faultString. The faultCode element can be cast into an int for comparison.

The above code adds the totalQueues headline variable to the view. It outputs the text "NO_SUCH_SAMPLER" if that error occurred.

XmlRpcValue table;
table[0][0] = "queueName";
table[0][1] = "currentSize";
table[0][2] = "maxSize";
table[0][3] = "currentUtilisation";
table[0][4] = "status";
table[1][0] = "queue1";
table[1][1] = 332;
table[1][2] = 30000;
table[1][3] = 0.11;
table[1][4] = "online";
...
parameters[0] = table;
c.execute("myManEnt.mySampler.myGroup-queues.updateEntireTable", parameters, result);

Creating the entire table in one go is done by defining the rows and columns in an array that is passed as a parameter.

parameters[0] = "totalQueues";
parameters[1] = 3;
c.execute("myManEnt.mySampler.myGroup-queues.updateHeadline", parameters, result);

parameters[0] = "queue2.currentUtilisation";
parameters[1] = 25;
c.execute("myManEnt.mySampler.myGroup-queues.updateTableCell", parameters, result);

Once the table has been created, values may be updated individually by using the updateHeadline or updateTableCell functions. Alternatively the whole table may be sent again. The method chosen is up to the developer and will depend on the frequency of updates and percentage of the table that changes each time.

When the entire table is sent, the API plug-in will calculate the changes and will only sent the updates required to the Geneos Framework.

Linking with the XML-RPC++ Library

To use XmlRpc++, the library should be downloaded from the SourceForge project page (http://sourceforge.net/projects/xmlrpcpp) and extracted to a suitable place. This should create an xmlrpc++x.x directory (where x.x is the version number) and within this directory a src and a test directory.

In order to compile the above code, it should be in a file named QueueSamplerClient.cpp in the test directory. The test/Makefile should be altered as follows:

TESTS = <as before> QueueSamplerClient

cd to the xmlrpc++x.x directory and then run:

make

Creating an API Plug-In

An API plug-in should be created in the same way as any other plug-in, by defining it in the gateway configuration as in the following example:

Figure 1 Basic Sampler Setup

Figure 2 Basic Managed Entity Setup

When the Netprobe is started or restarted, no views will initially be visible in Active Console since views are created by the external process. Once the view has been created, it will be empty until calls have been made to addTableColumn, addTableRow or updateEntireTable.

Running the API Client

Run the API client by passing it the name of the NetProbe host and the port number that NetProbe is listening on.

test/QueueSamplerClient hostname port

Open the ManagedEntity in ActiveConsole. Select the queues view. The value for queue2.currentSize should be increasing from 0 to 999.

The view will remain visible in ActiveConsole until the NetProbe restarts or the NetProbe configuration changes.

Introduction

The following sections provide concrete examples of how to construct custom views using the Geneos API in Java. The example view will show a set of dataviews for a particular component of a custom developed system and will look like this:

Although it is possible to write an API client without using any supporting libraries, it is easier to use an XML-RPC library. Here we will give examples of how to write a simple API client in Java using the org.apache.xmlrpc library. This example has been tested against version 3.1.2.

The following are the implementation steps:

• Write API client in Java
• Link with org.apache.xmlrpc library
• Create API plug-in using the Gateway setup
• Run the API client

Writing a Java Client

The Apache XML-RPC library for Java defines several classes to make it easy to call function on an XML-RPC server. Standard Java classes are used to represent data and Exceptions are thrown to represent errors. This step-by-step example shows how to use this library and is followed by the complete working program and an explanation of how to get started.

Insecure Netprobe

XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
config.setServerURL(new URL("http://server:port/xmlrpc"));
XmlRpcClient c = new XmlRpcClient();
c.setConfig(config);

Secured Netprobe

    XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
    config.setServerURL(new URL("https://server:port/xmlrpc"));
    XmlRpcClient c = new XmlRpcClient();
    c.setConfig(config);

    // Create a trust manager that does not validate certificate chains
    TrustManager[] trustAllCerts = new TrustManager[] { new X509TrustManager() {
    public X509Certificate[] getAcceptedIssuers() {
            return null;
    }

    public void checkClientTrusted(X509Certificate[] certs, String authType) {
    // Trust always
    }

    public void checkServerTrusted(X509Certificate[] certs, String authType) {
    // Trust always
    }
    } };

    // Install the all-trusting trust manager
    SSLContext sc = SSLContext.getInstance("SSL");
    // Create empty HostnameVerifier
    HostnameVerifier hv = new HostnameVerifier() {
            public boolean verify(String arg0, SSLSession arg1) {
                    return true;
            }
    };

    sc.init(null, trustAllCerts, new java.security.SecureRandom());
    HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
    HttpsURLConnection.setDefaultHostnameVerifier(hv);

This defines a client called c that will connect to server on port and use the URI /xmlrpc to handle the requests.

Vector parameters = new Vector();
String result = null;

The parameters to functions should be defined in a Vector. The return value from functions is an Object, but all the functions in this example will return a String. This will be explored further in a moment.

parameters.addElement("jqueues");
parameters.addElement("myGroup");

Strings can be added to the Vector in the standard way to form the parameters.

result = (String)c.execute("myManEnt.mySampler.createView", parameters);
System.out.println(result);

The execute function takes two parameters. The first is a String naming the function to call, the second is a Vector of parameters. Each parameter may be a String or a Vector. The return type is Object so that either a String or a Vector may be returned. It is cast into a String here as we know that we will be expecting a String. If a function returns a Vector then a ClassCastException will be thrown. If the return type is not known the instanceof operator can be used.

The above code creates the jqueues view in the mySampler plug-in. It will be listed under the group heading "myGroup".

parameters.removeElementAt(1);
parameters.setElementAt("totalQueues", 0);
try
{
 c.execute("myManEnt.mySampler.myGroup-jqueues.addHeadline", parameters);
}
catch (XmlRpcException e)
{
 if (e.code == NO_SUCH_SAMPLER)
 System.out.println(“NO_SUCH_SAMPLER”);
}

If the remote function returns an error then the execute method will throw an XmlRpcException. The error number is in a field called code and the error string is in the standard message for all Throwable objects and can be retrieved with e.getMessage().

The above code adds the totalQueues headline variable to the view. It outputs the text "NO_SUCH_SAMPLER" if that error occurred.

String[][] strTable =
{
 {"queueName","currentSize","maxSize","currentUtilisation","status"},
 {"queue1","332","30000","0.11","online"},
 {"queue2","0","90000","0","offline"},
 {"queue3","7331","45000","0.16","online"}
};
Vector table = new Vector();
for (int ix = 0; ix < strTable.length; ix++)
 table.addElement(new Vector(Arrays.asList(strTable[ix])));

parameters.setElementAt(table, 0);
c.execute("myManEnt.mySampler.myGroup-jqueues.updateEntireTable", parameters);	

An entire table may be created with a Vector of Vectors forming the rows and columns. The above code shows one way of creating the table. It is necessary to set the first parameter to be the table rather than passing the table directly to the function. Otherwise four parameters will be passed to the function (the headlines and three rows) instead of one parameter containing the table.

parameters.setElementAt("totalQueues", 0); // Headline variable name
parameters.addElement("3"); // New value for the headline
c.execute("myManEnt.mySampler.myGroup-jqueues.updateHeadline", parameters);

parameters.setElementAt("queue2.currentUtilisation", 0); // TableCell variable name
parameters.setElementAt("25", 1); // New value for the TableCell
c.execute("myManEnt.mySampler.myGroup-jqueues.updateTableCell", parameters);

Once the table has been created, values may be updated individually by using the updateHeadline or updateTableCell functions. Alternatively the whole table may be sent again. The method chosen is up to the developer and will depend on the frequency of updates and percentage of the table that changes each time.

When the entire table is sent, the API plug-in will calculate the changes and will only sent the updates required to the Geneos Framework.

Linking with the Apache XMLRPC Library

To use the org.apache.xmlrpc classes, the library should be downloaded by following the links from http://ws.apache.org/xmlrpc/download.html and extracted to a suitable place. The classes are pre-compiled into a jar file if the non-src version is downloaded.

On extraction, an apache‑xmlrpc-x.x.x directory will have been created, and the lib directory within it will contain a number of jar files (where x.x.x is the version number).

In order to compile this code, it should be in a file named QueueSamplerClient.java in the same directory as the jar files.

Go to the xmlrpc-x.x.x/lib directory and then run the following OS-dependent command, remembering to substitute the version numbers of the library being used.

On Windows:

javac -classpath ".;xmlrpc-client-x.x.x.jar;xmlrpc-common-x.x.x.jar" QueueSamplerClient.java

Or , on UNIX-based systems:

javac -classpath ".:xmlrpc-client-x.x.x.jar:xmlrpc-common-x.x.x.jar" QueueSamplerClient.java

Creating an API Plug-In

An API plug-in should be created in the same way as any other plug-in, by defining it in the gateway configuration as in the following example:

Figure 3 Basic Sampler Setup

Figure 4 Basic Managed Entity Setup

When the NetProbe is started or restarted, no views will initially be visible in ActiveConsole since views are created by the external process. Once the view has been created, it will be empty until calls have been made to addTableColumn, addTableRow or updateEntireTable.

Run the API Client

Run the API client by passing it the name of the NetProbe host and the port number that NetProbe is listening on, remembering to substitute the version numbers of the library being used.

On Windows:

java -classpath ".;xmlrpc-client-x.x.x.jar;xmlrpc-common-x.x.x.jar;ws-commons-util-x.x.x.jar" QueueSamplerClient hostname port

Or, on UNIX-based systems:

java -classpath ".:xmlrpc-client-x.x.x.jar:xmlrpc-common-x.x.x.jar:ws-commons-util-x.x.x.jar" QueueSamplerClient hostname port

Open the ManagedEntity in ActiveConsole.

Select the jqueues view. The value for queue2.currentSize should be increasing from 0 to 999.

The view will remain visible in ActiveConsole until the NetProbe restarts or the NetProbe configuration changes.

Introduction

API Streams may be used to send logs from external processes through the File Keyword Monitoring plug-in, which then allows rules to be set on it. The API-STREAMS plug-in is separate from the API plug-in, but function calls are made in the same way, through XML-RPC.

Creating an API Streams Plug-In

An API Streams plug-in should be created in the same way as any other plug-in, by defining it in the gateway configuration as in the following example:

Figure 5 Basic API- Streams Sampler Setup

Figure 6 Basic Managed Entity Setup

The streams should be named in the sampler descriptor using the STREAMS sampler parameter as shown above. These names will be used to refer to the streams in the sampler (example with FKM is below).

Each stream uses a buffer to hold the messages between the time the API client writes to the stream and the time the sampler reads from the stream. It may optionally be set using the "Buffer size" sampler parameter (See API-Streams Configuration: bufferSize). This buffer refers to the number of messages that may be stored. The default buffer is 1000 messages. If the buffer becomes full then the API client will receive a STREAM_BUFFER_FULL error. From this point until the sampler reads some messages from the stream, each line that is added to the buffer will force the oldest unread message to be dropped from the buffer. When the sampler next reads from the stream, it will get an additional message indicating how many messages have been lost.

Sampler debug view

The "Create view" sampler parameter may be used to switch on the debug view (See API-Streams Configuration: createView).

Headline Legend

Table Legend

Because more than one sampler may be configured to read from the stream and each sampler has its own reading position in the buffer, the currentBufferSize and totalMessagesLost columns reflect the state of the slowest sampler.

Using the API to Write to Streams

Calls to the streams may be made in exactly the same way as with the standard API.

parameters[0] = "This is a line to be sent through a stream to FKM";
if (c.execute("myManEnt.myStreamsSampler.a.addMessage", parameters, result))
 std::cout << "Result: " << result << "\n";

This will append the log message to the stream called 'a' in the plug-in called 'myStreamsSampler'.

Heartbeats

It is sometimes necessary to be alerted when no updates are received for a particular Sampler, as this can be an indication that an external process has stopped functioning.

Clients may call the signOn method to commit to providing updates for a Sampler. The maximum number of seconds between updates is specified as a parameter. This may be between 1 second and 86400 seconds (24 hours) inclusive.

The samplingStatus is shown in ActiveConsole at the bottom of each view created by the API. It is initially set to "OK" and will remain that way if no clients have signed on. If a client has signed on and subsequently stops providing updates then the samplingStatus of each view belonging to that Sampler will display "FAILED: No heartbeat from the client in the last xx seconds", where xx is the number of seconds since the last update. If this is above 60 seconds then the time will be given in minutes. If an update is then received then the sampling status will be returned to "OK".

For example:

parameters[0] = 120;
if (c.execute("myManEnt.mySampler.signOn", parameters, result))
 std::cout << "Result: " << result << "\n";

would commit this sampler to providing updates every 120 seconds. At any point from then on, if the last method call to the Sampler was received over 2 minutes ago then the samplingStatus will be set to FAILED.

If a client has no data updates for the period, then they may call the heartbeat() method on the Sampler.

When a client no longer wishes to commit to providing updates, it may call the signOff method. If it wishes to change the time it has committed to, it may call the signOn method again without having to sign off first.

Calling signOff or heartbeat when not signed on will return "OK" but will have no effect on the view.

NetProbe Function Calls

parameters[0] = "myManEnt";
if (c.execute("_netprobe.managedEntityExists", parameters, result))
 std::cout << "Result: " << result << "\n";

parameters[0] = "myManEnt.mySampler";
if (c.execute("_netprobe.samplerExists", parameters, result))
 std::cout << "Result: " << result << "\n";

Expect View

Heartbeats can be used to detect an application stopping after it has created API views, but if an application has never started then there will be no views present to set rules on. Expect view functionality addresses this problem by being able to specify views that you expect to be created.

The name the name of the view and the group heading should be specified in the Expect Views section of the plugin setup. Any number of Expect Views can be specified. See API Plug-In Configuration.

Summary View

The summary view can be used for detecting missing views by setting a rule on the totalViews headline e.g. you may expect 10 view to be created but total views only shows 8. The summary view also shows the last time any command was sent to the sampler and to each view, this is to detect processes that are no longer sending information to the netprobe.

Security

expectViews

This parameter specifies a list of views that are expected to be created. These views will be created by the probe even if there has been no requests to create these views sent by the feeding application. There can be any number of these views. (See section Expect View)

Mandatory: No

expectViews > expectView

This parameter specifies an individual view that you expect to be created. The view definition is composed of both a name and a group.

Mandatory: No

expectViews > expectView > view

Specifies the name of a view that you expect to be created.

Mandatory: Yes (if an Expect View has been specified)

expectViews > expectView > group

Specifies the group to which to add view that you expect to be created.

Mandatory: Yes (if an Expect View has been specified)

expectViewDelay

This specifies the amount of time (in seconds) to wait after starting the sampler before creating expected views that have not been created by the feeding application.

parameters

This provides a list of name value pairs that are stored in the probe and can be queried by the feeding application using the "entity.sampler.getParameter" API call. (See Section API Technical Reference)

Mandatory: No

parameters > parameter

This specifies an individual parameter that is stored in the probe. The parameter is composed of a name and a value.

Mandatory: No

showSummaryView

The summary view reports on all views that have been published by api processes. This view displays:

Headlines: total views (published by all api processes to this sampler) and heartbeat rate

Rows: Name of the view (published by an api process), last time that view was updated and duration in seconds since the last update.

Rules can be set on the total views to detect when all the required views have not been created or duration since last update to detect views that have "frozen" i.e. no more updates are being received.

The summary view can either be displayed all the time or never. The default for the summary view is never.

Mandatory: No

streams

This parameter specifies a list of streams that should be created. These can be written to by the feeding application. (See Using the API to Write to Streams)

Mandatory: Yes

bufferSize

This parameter specifies the maximum number of items to hold in memory at a time. If the sampler is not configured to read the stream often enough for the data rate then this parameter may need to be increased, otherwise the feeding application will not be able to write to the stream.

createView

This parameter specifies whether a debug view should be created that shows how many messages are passing through each stream and how many messages have been dropped.

API Streams Function Calls

entity.sampler.stream.addMessage

string entity.sampler.stream.addMessage(string message)

Adds a new message to the end of the stream.

GATEWAY_NOT_CONNECTED, NO_SUCH_SAMPLER, NO_SUCH_STREAM, STREAM_BUFFER_FULL

string entity.sampler.stream.signOn(int seconds)

GATEWAY_NOT_CONNECTED, NO_SUCH_SAMPLER, NUMBER_OUT_OF_RANGE

string entity.sampler.stream.signOff()

GATEWAY_NOT_CONNECTED, NO_SUCH_SAMPLER

string entity.sampler.stream.heartbeat()

GATEWAY_NOT_CONNECTED, NO_SUCH_SAMPLER

NetProbe Function Calls

_netprobe.managedEntityExists

boolean _netprobe.managedEntityExists(string managedEntity)

Checks whether a particular Managed Entity exists on this NetProbe containing any API or API-Streams samplers.

_netprobe.samplerExists

boolean _netprobe.samplerExists(string sampler)

Checks whether a particular API or API-Streams sampler exists on this NetProbe.

_netprobe.gatewayConnected

boolean _netprobe.gatewayConnected()

Checks whether the Gateway is connected to this NetProbe.

Gateway Function Calls

_gateway.addManagedEntity

string _gateway.addManagedEntity(string managedEntity, string dataSection)

Adds the managed entity to the particular data section. The data section should be #include'd into the MANAGED_ENTITIES section of the gateway setup. As long as a Gatway is connected, this method will always return "OK". If the managed entity already exists, a warning will be seen in the Gateway log.

GATEWAY_NOT_CONNECTED