This document covers the following topics:

• General Information

• Setting Up EntireX Broker

• Setting Up the EntireX Adapter

• Configuration for Application Monitoring

• Starting and Stopping the Application Monitoring Data Collector

• Callback User Exit

---

General Information

The collection of response times and other measuring data from your distributed applications in real time requires that you set up various components for application monitoring. EntireX Broker and/or the EntireX Adapter serve as the central components which control the data flow. Their configuration defines the following: whether application monitoring is generally enabled or disabled, the services that are used for monitoring (only for EntireX Broker), and the Application Monitoring Data Collector to which the measuring data is sent.

In addition, your applications need to be prepared for the collection and distribution of measuring data. This is automatically ensured when you use the appropriate EntireX components which support application monitoring. Further configuration on the side of the application is not required.

Setting Up EntireX Broker

EntireX Broker controls the measuring data flow. Using specific attributes in the broker attribute file, the broker can be configured to enable application monitoring for selected services. There are broker-specific and service-specific attributes for application monitoring, and there are also application monitoring-specific attributes. For detailed information, see Broker Attributes.

Configuration example:

DEFAULTS = BROKER 
  APPLICATION-MONITORING = YES 

DEFAULTS = APPLICATION-MONITORING 
  COLLECTOR-BROKER-ID = server12:57900 

DEFAULTS = SERVICE 
  APPLICATION-MONITORING-NAME = Payroll_Application
  CLASS = RPC, SERVER = HR, SERVICE = CALLNAT, APPLICATION-MONITORING = YES, APPLICATION-MONITORING-NAME = HR_Application
  CLASS = RPC, SERVER = *, SERVICE = CALLNAT, APPLICATION-MONITORING = YES

With this example configuration, application monitoring is enabled for all RPC/*/CALLNAT services. The service RPC/HR/CALLNAT uses the application monitoring name "HR_Application", all other services use the name "Payroll_Application". The Application Monitoring Data Collector runs on a host with the name "server12" and uses the port 57900.

Setting Up the EntireX Adapter

The EntireX Adapter automatically supports application monitoring for the following connection types:

• EntireX RPC Connection

• EntireX RPC Listener Connection

If you want to use application monitoring with the following connection types, you have to change the configuration of the EntireX Adapter. See EntireX Adapter Connections in the EntireX Adapter documentation.

• EntireX Direct RPC Connection

• EntireX Direct RPC Listener Connection

• IMS Connect Connection

• CICS ECI Connection

Configuration for Application Monitoring

The configuration file entirex.appmondc.properties controls the startup of the Application Monitoring Data Collector. It is located in the config directory of your EntireX installation.

As a rule, it is not necessary to change the settings in this file after the installation. However, if required, you can change the following parameters:

Parameter	Description
entirex.appmondc.port	The TCP/IP port on which the Application Monitoring Data Collector accepts the monitoring data. This value is set during the installation of the Application Monitoring Data Collector.
entirex.appmondc.directory	The name of the directory which will contain the CSV data files. The default value is <EntireX-install-dir>/appmondc/. A data file has the name appmon<YYYYMMDD>.<HHMMSS>.csv. In addition, an overview file with the name appmon.overview.v1.csv is created.
entirex.appmondc.loglevel	The log level for the log files. Possible values are: OFF FATAL ERROR WARNING INFO DEBUG TRACE The default value is ERROR. Log files are always stored in the directory <EntireX-install-dir>/appmondc/. This is independent of the setting of the entirex.appmondc.directory parameter.
entirex.appmondc.maxlines	The maximum number of rows per CSV data file. If the limit is reached, a new file is created. The default value is 100000.
entirex.appmondc.filesperday	Automatically create a new CVS data file every day. The default value is no.
entirex.appmondc.usezeroasnullvalue	Use "0" instead of an empty entry as the null value for all numeric KPI values in the CSV file. The default value is no.
entirex.appmondc.callback.class	Java class name for the callback user exit.
entirex.appmondc.callback.classpath	Classpath name in URL notation for the callback user exit.

Starting and Stopping the Application Monitoring Data Collector

UNIX

The scripts mentioned below are located in the bin directory of your EntireX installation. By default, this is /opt/softwareag/entirex/bin.

To start the Application Monitoring Data Collector

• Run the script appmondc.bsh from a shell.

To stop the Application Monitoring Data Collector

• Run the script stopappmondc.bsh from a shell.

Windows

The Application Monitoring Data Collector is installed as an application and as a Windows service. During the installation, you can specify that the Windows service is to be started automatically. The name of this service is "Software AG EntireX Application Monitoring Data Collector 10.1".

To start the Application Monitoring Data Collector as an application

• Choose the following from the Windows Start menu:

  Programs > Software AG > Start Servers > Start EntireX Application Monitoring Data Collector 10.1

  Or:
  Run the script appmondc.bat which is located in the bin directory of your EntireX installation.

To stop the Application Monitoring Data Collector (service and application)

• Choose the following from the Windows Start menu:

  Programs > Software AG > Stop Servers > Stop EntireX Application Monitoring Data Collector 10.1

  Or:
  Run the script stopappmondc.bat which is located in the bin directory of your EntireX installation.

Callback User Exit

The Application Monitoring Data Collector provides a callback functionality for the processing of incoming events. A user exit can be specified to implement the callback. Whenever the Data Collector receives a monitoring event, the KPI values are writen to the CSV file and the callback is invoked. The KPI values of the event are passed to the callback. Possible use cases are:

• trigger an action based on specific KPI values (e.g. the KPIs indicate a failed request)

• write the KPI values to another data store or in a format that is different from a CSV file

To enable the user exit callback, use the property entirex.appmondc.callback.class to specify the class name of the user exit implementation. The class is loaded using the standard classpath. You can specify a separate classpath with the property entirex.appmondc.callback.classpath. Note that for the classpath, a file or HTTP URL must be specified (on Windows replace the "\" character with "/"). Your user exit class must implement the Java interface com.softwareag.entirex.appmondc.DataCollectorCallback. This Java interface has the following methods:

/**
 * Initialize the callback handler.
 * @param directory The name of the directory that will contain the CSV data files (set by property "entirex.appmondc.directory")
 * 
 * @throws Exception
 */
public void start(String directory) throws Exception;

/**
 * Stop the callback handler.
 */
public void stop();

/**
 * Process an event. This corresponds to an entry in the CSV file.
 * The map contains all KPIs which have a value.
 * The key names of the map are identical to the KPI names.
 * 
 * @param kpis The KPI map.
 * @throws Exception
 */
public void processEvent(Map<String, String> kpis) throws Exception;