Connectivity plug-ins can add any number of user-defined status values which are reported as part of the correlator's status information from the REST API, the engine_watch tool, the Engine Client API, and from the EPL Management interface. Status values can be reported by transports, codecs, or dynamic chain managers.

If the status keys follow the conventions listed in Monitoring the KPIs for EPL applications and connectivity plug-ins, the status and KPIs of your application's connectivity plug-ins can be displayed by Command Central.

For example, a transport plug-in might report a status value to indicate whether it is currently online and working correctly, or failed. Or it can report numeric KPIs indicating the number of messages sent towards the host (correlator) and towards the transport. A dynamic chain manager might report information about a connection it maintains, and perhaps provide some KPI statistics aggregated across all the transport instances it is managing.

To report status information, create a status item by calling the getStatusReporter().createStatusItem(...) method on your plug-in class, specifying the key for this status item and its initial value, and store the resulting StatusItem object in a field so its value can be updated as necessary. Status items are automatically removed when a transport or codec plug-in is shut down or when the chain is destroyed (in C++, this assumes the StatusItem is held by a std::unique_ptr in a member of the plug-in class, as we recommend). Be sure to use a unique name to identify the plug-in in each status key; we recommend using the chainId and pluginName as a prefix for transport and codec plug-ins, or the managerName for chain managers. Status keys will have leading and trailing whitespace stripped. Keys cannot be empty. For example, in Java:

Or in C++:

We recommend using the STATUS_* constants provided on StatusReporter for values of ".status" items, to provide consistency and allow the status to be represented correctly if viewed using Command Central.

In addition to the StatusItem interface, there is a separate method for atomically setting multiple related items in a single call (for example, a status and an error message). But as the StatusItem method is more efficient, it should be used in most cases, especially for items that might be updated frequently such as message counters.

All user-defined status values are currently represented as strings, but for convenience when reporting KPI numbers, an overload of setStatus exists that accepts an integer argument for the value, which is automatically converted to a string by the method. There is also an increment() method.

For transports and codecs, status reporting is only permitted when your plug-in provides the TransportConstructorParameters and CodecConstructorParameters constructors. It is not supported when using the older deprecated constructors.

For examples of how to report status information from a connectivity plug-in, see the samples\connectivity_plugin\cpp\httpclient and samples\connectivity_plugin\java\HTTPServer directories of your Apama installation.

See the StatusReporter interface in the API Reference for Java (Javadoc) and API Reference for C++ (Doxygen) for more information about how to report status.

See also Using the Management interface for information about how status values can be set and retrieved by EPL code.

For other ways to view the correlator's status, see Managing and Monitoring over REST and Watching correlator runtime status