Message Tracker Plugin API

Intended Audience Copied

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

Communications from Reporting Agents Copied

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:

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 Copied

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 Copied

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:

>
>
> **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, 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 Copied

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:

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 Copied

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 Copied

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 Copied

The following related documents are available:

["Geneos"] ["Geneos > Netprobe"] ["Technical Reference"]

Was this topic helpful?