Message Tracker Plug-in API - Technical Reference

Intended Audience

This document is intended to be read by client developers who have read the GENEOS - Message Tracker Plug-in documentation.

Communications from Reporting Agents

The Message Tracker plug-in provides an XML-RPC interface that allows external adapters to provide information about messages to be tracked. There are currently 3 types of XmlRpc method calls which will results in messages being processed by the plug-in:

receivedFromAPI_RTT_Adapter - this is an internal method used by the Geneos framework to route messages to the XmlRpc interface of the plug-in. It is not recommended that the user make use of this method.

receivedFromAPI_RTT_DB_Adapter - this is a method that a client should use when they want to send all the details of a message themselves to the plug-in. They are not interested in the adapter parsing their message; they provide a parsed message themselves. They can additionally specify in the actual message body whether they want their message to be logged to a database or not.

messageTracker_Adapter_Message - this is a method that a client can use when they wish to provide a number of parameters but control via the sampler set-up, how these parameters are used. A client can also control whether these messages get logged or not to a database, by changing their sampler set-up accordingly.

We discuss these methods in more detail below. More information about sending XmlRpc messages can be found in the 'Geneos - XmlRpc Api User Guide and Technical Reference'

The 'receivedFromAPI_RTT_Adapter' method

This method is prefixed with the name of the entity and the name of the sampler when invoked and has the following parameters:

string entity.sampler.receivedFromAPI_RTT_Adapter (
        string Checkpoint,
        struct IDs,
        string Description,
        string Timestamp,
        string Category,
        string[] Destinations)

The arguments which are passed in by the client represent the following information:

Check point: This is the name of the checkpoint that the current Message was seen at.

IDs: A set of message identifiers. Each identifier should uniquely identify the message. Each identifier must be given a name.

Description: A short string describing the message for human readers. This message will only be used if the sampler is the initial sampler to process the message, however if a parent sampler is disconnected than any sampler can become an initial sampler, so all clients should provide this string.

Timestamp: The time when the message was seen by the external adapter. This should be in the format xxxxxxxxxx.yyyyyy (seconds and microseconds since Jan-01 1970, the UNIX epoch).

Category. This provides a string that is used to categorise the Latency statistics in the Latency View. If this is blank then the messages will not be categorised in the Latency View.

Destination: The destination of the message. This will be one of the following:

ANY: This implies that the message can go to any of the configured checkpoint. This differs from ALL in that it is expected to go only to one of the downstream check points. (It should be noted that if it is sent to more than one check point this will not be tracked).

ALL: This implies that the message must go to all the downstream checkpoints, and it will be listed as lost if any one of the downstream checkpoints fails to report the arrival of the message in a given amount of time.

A list of Check points: The list will be composed of check point names. The message must be passed to all specified downstream checkpoints in order for the message not to be listed as lost. If the message arrives at a downstream checkpoint that is not specified in the list, but is listed as a child of the current Latency-RTT, then that child Latency-RTT will list the message as misdirected.

The possible set of return values includes the following: OK, WRONG_PARAM_COUNT, NO_SUCH_SAMPLER, HOST_NOT_TRUSTED, GATEWAY_NOT_CONNECTED, STREAM_BUFFER_FULL, NO_XML_SENT

An example method call is provided below:

POST /xmlrpc HTTP/1.1
Host: 127.0.0.1
Content-Type: text/xml
Content-length: 704

<methodCall>
        <methodName>MyEntity.MySampler.receivedFromAPI_RTT_Adapter</methodName>
        <params>
                <param><value><string>CP1</string></value></param>
                <param><value>
                <struct>
                        <member>
                                <name>CLIENT ID</name>
                                <value><string>1234-2345-2344</string></value>
                        </member>
                        <member>
                                <name>INTERNAL ID</name>
                                <value><string>ASD 2344</string></value>
                        </member>
                </struct>
                </value></param>
                <param><value><string>1234-2345-2344 DMA Order</string></value></param>
                <param><value><string>1270900823.293492</string></value></param>
                <param><value><string>ASD</string></value></param>
                <param><value><string>ANY</string></value></param>
        </params>
</methodCall>

The 'receivedFromAPI_RTT_DB_Adapter' method

This method is prefixed with the name of the entity and the name of the sampler when invoked and has the following parameters:

string entity.sampler.receivedFromAPI_RTT_Adapter (
        string Checkpoint,
        struct IDs,
        string Description,
        string Timestamp,
        string Category,
        string[] Destinations,
        struct Attributes,
        bool LogToDB

The arguments which are passed in by the client represent the following information:

Check point: This is the name of the checkpoint that the current Message was seen at.

IDs: A set of message identifiers. Each identifier should uniquely identify the message. Each identifier must be given a name.

Timestamp: The time when the message was seen by the external adapter. This should be in the format xxxxxxxxxx.yyyyyy (seconds and microseconds since Jan-01 1970, the UNIX epoch).

Category. This provides a string that is used to categorise the Latency statistics in the Latency View. If this is blank then the messages will not be categorised in the Latency View.

Destination: The destination of the message. This will be one of the following:

ANY: This implies that the message can go to any of the configured checkpoint. This differs from ALL in that it is expected to go only to one of the downstream check points. (It should be noted that if it is sent to more than one check point this will not be tracked).

ALL: This implies that the message must go to all the downstream checkpoints, and it will be listed as lost if any one of the downstream checkpoints fails to report the arrival of the message in a given amount of time.

A list of Check points: The list will be composed of check point names. The message must be passed to all specified downstream checkpoints in order for the message not to be listed as lost. If the message arrives at a downstream checkpoint that is not specified in the list, but is listed as a child of the current Latency-RTT, then that child Latency-RTT will list the message as misdirected.

Attributes: A set of name-value pairs, similar to the IDs parameter above. These values will be logged to the database if logging has been configured and enabled in the sampler setup.

LogToDB: Whether the message should be logged to the database specified in the sampler set-up or not.

The possible set of return values includes the following: OK, CLIENT_NOT_TRUSTED, NO_XML_SENT, NO_SUCH_SAMPLER, WRONG_PARAM_COUNT

An example method call is provided below:

POST /xmlrpc HTTP/1.1
Host: 127.0.0.1
Content-Type: text/xml
Content-length: 1101

<methodCall>
        <methodName>MyEntity.MySampler.receivedFromAPI_RTT_DB_Adapter</methodName>
        <params>
                <param><value><string>CP1</string></value></param>
                <param>
                        <value>
                                <struct>
                                        <member>
                                                <name>CLIENT ID</name>
                                                <value><string>1234-2345-2344</string></value>
                                        </member>
                                        <member>
                                                <name>INTERNAL ID</name>
                                                <value><string>ASD 2344</string></value>
                                        </member>
                                </struct>
                        </value>
                </param>
                <param><value><string>1234-2345-2344 DMA Order</string></value></param>
                <param><value><string>1270900823.293492</string></value></param>
                <param><value><string>ASD</string></value></param>
                <param><value><string>ANY</string></value></param>
                <param>
                        <value>
                                <struct>
                                        <member>
                                                <name>ATR_1_NAME</name>
                                        <value><string>ATR_1_VALUE</string></value>
                                        </member>
                                        <member>
                                                <name>ATR_2_NAME</name>
                                                <value><string>ATR_2_VALUE</string></value>
                                        </member>
                                </struct>
                        </value>
                </param>
                <param><value><boolean>1</boolean></value></param>
        </params>
</methodCall>

The 'messageTracker_Adapter_Message' method

This method is prefixed with the name of the entity and the name of the sampler when invoked and has the following signature.

string entity.sampler.messageTracker_Adapter_Message (
        string AdapterName,
        string Timestamp,
        struct Fields)

The arguments which are passed in by the client represent the following information:

Adapter: The name of the adapter which should process the information being sent via the XmlRpc method.

Timestamp: The time when the message was seen by the external adapter. This should be in the format xxxxxxxxxx.yyyyyy (seconds and microseconds since Jan-01 1970, the UNIX epoch).

Fields: A set of name-value pairs which are referenced by the adapter configuration for the adapter named in the first parameter. These fields will be interpreted as either IDs or Attributes accordingly.

An example method is provided below

POST /xmlrpc HTTP/1.1
Host: 127.0.0.1
Content-Type: text/xml
Content-length: 509

<methodCall>
        <methodName>MyEntity.MySampler.messageTracker_Adapter_Message</methodName>
        <param><value><string>MyFauxAdapter</string></value></param>
        <param><value><string>1270900823.293492</string></value></param>
        <param>
                <value>
                        <struct>
                                <member>
                                        <name>NAME_1</name>
                                        <value><string>DATA_1</string></value>
                                </member>
                                <member>
                                        <name>NAME_2</name>
                                        <value><string>DATA_2</string></value>
                                </member>
                        </struct>
                </value>
        </param>
</methodCall>

Warnings

When the user wants to configure an adapter for use with the receivedFromAPI_RTT_DB_Adapter or messageTracker_Adapter_Message method, they must ensure that the sourceType and the formatType of the adapter be set to xmlrpc. The netprobe will write an error message to its log file if a misconfiguration is detected.

Security

The Netprobe can be started using a -secure flag (See 'Geneos Secure Communications' guide). If this is done then the XML-RPC client used must use HTTPS rather than HTTP as a transport protocol to deliver the XML-RPC messages.

References

The following related documents are available:

GENEOS - Message Tracker Plug-in
GENEOS - XML-RPC API - User Guide and Technical Reference.
XML-RPC Specification