Apama 10.15.0 | Deploying and Managing Apama Applications | Deploying Apama Components with Command Central | Monitoring Apama from Command Central | Monitoring the KPIs for EPL applications and connectivity plug-ins
 
Monitoring the KPIs for EPL applications and connectivity plug-ins
In Command Central, you can monitor the status and KPIs of one or more parts of your application, each of which will be represented in Command Central as a subcomponent of the correlator instance. Status can be reported by both EPL code and connectivity plug-ins. In Command Central, each component can show status (for example, online/offline) and up to three numeric KPIs.
To monitor the KPIs of an application component:
1. Specify the components of your application to be monitored using the Application KPI configuration type. Specify the subcomponent_identifier in the Monitor Applications field. You can specify multiple names using a comma separator. Each subcomponent_identifier specified here is represented as a subcomponent under the correlator instance. You can update the Application monitoring configuration in the Command Central web interface and command line interface.
To update the configuration in the command line interface:
sagcc update configuration data local Apama-correlator-myCorrelator
APAMA-CORRELATOR-APP-MONITORING -i C:\EPLService.properties
Example format of a properties file for the Application KPI configuration type:
MyEPLService, MyEPLService1, MyEPLService2,
MyConnectivityChain1.MyConnectivityTransportPlugin
2. Update your application's EPL files to report status and KPIs for each component of your EPL application by calling the EPL API com.apama.correlator.Component.setUserStatus.
For more information, see API Reference for EPL (ApamaDoc) and Using the Management interface.
If using Software AG Designer, add the Correlator Management bundle to make this event definition available to your project. For the EPL application subcomponent to report the status or KPIs in Command Central, you must follow certain conventions in the EPL files as mentioned in the following list:
*EPL convention. com.apama.correlator.Component.setUserStatus(subcomponent_identifier +".status", status);
Description. Provides an indication of the health of the component, for example, whether it is still STARTING, has FAILED or is ONLINE and fully operational. The subcomponent_identifier is a user-defined unique string prefix to identify a component of an EPL application. This unique string is used to identify the components that are monitored in the correlator's Application KPI configuration in Command Central.
Values: STARTING, ONLINE, FAILED, UNKNOWN (the value OFFLINE is also permitted for backwards compatibility but no longer recommended for use)
Default value: UNKNOWN
Example:
constant string SUBCOMPONENT_ID := "MyEPLService";
com.apama.correlator.Component.setUserStatus(
SUBCOMPONENT_ID +".status", "ONLINE");
*EPL convention. com.apama.correlator.Component.setUserStatus(subcomponent_identifier +".KPIs", KPI_list);
Description. The KPI_list is a comma-separated list of user status keys, identifying the numerical KPIs that should be displayed for this subcomponent by monitoring tools such as Command Central.
Example:
constant string KPI_USERS := "MyEPLService active users";
constant string KPI_ERRORS := "MyEPLService errors in last hour";
constant string KPI_MEMORY := "MyEPLService memory used";
constant string KPI_MESSAGE_RATE := "MyEPLService message rate";
com.apama.correlator.Component.setUserStatus(
SUBCOMPONENT_ID +".KPIs", ",".join([KPI_USERS, KPI_ERRORS,
KPI_MEMORY, KPI_MESSAGE_RATE]);
Only the first three KPIs are displayed in the Command Central web interface.
*EPL convention. com.apama.correlator.Component.setUserStatus(KPI_identifier, "0");
Description. Publishes a KPI value for a monitored component of the EPL application. The KPI_identifier is a user-defined unique identifier to identify the KPI which must be specified in subcomponentid.KPIs for the subcomponent it applies to. It is recommended that this string includes the subcomponent_identifier to differentiate from other subcomponents. Also, define an EPL string constant for each KPI so that it is convenient to add various suffixes if you wish to monitor optional information such as units and maximum value of this KPI. The KPI value can be an integer or a float, represented as an EPL string.
Default value: 0
Example:
string KPI_MESSAGE_RATE := SUBCOMPONENT_ID+" message rate";
com.apama.correlator.Component.setUserStatus(
KPI_MESSAGE_RATE, messageRate.toString());
*EPL convention. com.apama.correlator.Component.setUserStatus(KPI_identifier +".units", name);
Description. Name to be used for displaying the units against which the KPI numbers are reported. Command Central displays these units in the graphs.
Example:
com.apama.correlator.Component.setUserStatus(
KPI_MESSAGE_RATE +".units", "evt/sec");
*EPL convention. com.apama.correlator.Component.setUserStatus(KPI_identifier +".max", value);
Description. Represents the maximum value of the KPI that is published. This defines the maximum point of the vertical axis on which the KPI value is displayed. The value attribute must be a string representation of an integer or float.
Default value: VALUE +1
Example:
com.apama.correlator.Component.setUserStatus(
KPI_MESSAGE_RATE +".max", "1000");
*EPL convention. com.apama.correlator.Component.setUserStatus(KPI_identifier +".marginal", value);
Description. Represents the marginal value of the KPI that is published. When the KPI value is above this level, the KPI will be shown with a warning alert. The value attribute must be a string representation of an integer or float.
Default value: VALUE +1
Example:
com.apama.correlator.Component.setUserStatus(
KPI_MESSAGE_RATE +".marginal", "100");
*EPL convention. com.apama.correlator.Component.setUserStatus(KPI_identifier +".critical", value);.
Description. Represents the critical value of the KPI that is published. When the KPI value is above this level, the KPI will be shown with an error alert. The value attribute must be a string representation of an integer or float.
Default value: VALUE +1
Example:
com.apama.correlator.Component.setUserStatus(
KPI_MESSAGE_RATE +".critical", "500");
*EPL convention. com.apama.correlator.Component.setUserStatus(KPI_identifier +".display", name);.
Description. Represents the name to be used as a display name in Command Central when KPI names are longer.
Default value: KPI_identifier
Example:
com.apama.correlator.Component.setUserStatus(
KPI_MESSAGE_RATE +".display", "Message Rate");
3. Connectivity plug-ins can be written to report status and KPIs using the StatusReporter interface, typically using the plug-in's chainId+"."+pluginName as the subcomponent_identifier. The conventions listed above should be followed.
For more information, see User-defined status reporting from connectivity plug-ins.
Note: 
The status keys, subcomponent identifiers, and the suffixes .status, .KPIs, .max, .min and .display are case sensitive.