eG Administration
 

Configuring Measures for a JMX Test

Java-based web servers and application servers (eg., Tomcat, JBoss, WebLogic, WebSphere, etc.) are common place in many IT infrastructures. Though eG Enterprise provides comprehensive monitoring models for most of these servers, some administrators might want to monitor certain additional server attributes that are not supported out-of-the-box by the eG agent. Likewise, in some other environments, custom Java applications may operate for which eG Enterprise may not provide out-of-the-box monitoring support.

To enable administrators to extend the capabilities of the eG agent to report on additional attributes related to Java-based web and application servers, and to easily develop custom monitoring models for unsupported Java applications, eG Enterprise offers the JMX test type. Jmx (Java Management Extensions) is a Java technology that enables external programs like the eG agent to pull out performance metrics from a target Java application/server. By adding a test of type JMX, you can easily equip the eG agent with the ability to leverage the JMX technology for connecting to any Java application/server, and reading the current values of those attributes of the target that interest you.

Note:

Prior to adding a new JMX test, you need to enable the JMX support for the JRE of the target application. To know how, please refer to Extending the Monitoring Capabilities of eG Enterpise document.

This page enables you to configure the measures for a test of type JMX. Click the Add New Measure button in the Measure tab of the NEW TEST DETAILS page to add a measure.

This page allows you the flexibility to choose from multiple methods for configuring the measures of the new JMX test(i.e., you can choose the method from the Measure Selection Options list); these methods are as follows:

  • MBean Auto Discovery
  • Load MBeans from File
  • Manual Entry

The procedure for configuring measures for a JMX test may slightly vary depending upon the option chosen from the Measure Selection Options list. Discussed hereunder are the individual options offered by the Measure Selection Options list, and how your choice will impact measure configuration for a JMX test.

MBean Auto Discovery

The MBean Auto Discovery option enables the eG manager to automatically discover the domains and MBeans supported by a target Java application, so that you can configure any of the Mbean attributes as a measure with minimal manual effort. Select this option if you do not know the exact Mbean attribute name to be configured as a measure for a new JMX test. When this option is chosen, you will have to additionally specify the following in the NEW TEST DETAILS page as specified below:

  • Specify the host name / IP address of the system hosting the Java application in the Host Name / IP text box.

  • Indicate the port at which the JMX of the Java application listens, in the JMX Remote Port text box.

  • In the JNDI Name text box, specify the lookup name for connecting to the JMX connector. By default, this is set to jmxrmi.

  • By default, both User name and Password parameters are set to none. However, if JMX requires authentication only (but no security), then, ensure that these fields are configured with the credentials of a user with read-write access to JMX. To know how to create this user, refer to Extending the Monitoring Capabilites of eG Enterprise document.

  • Finally, click the Start discovery button.

  • Doing so will automatically populate the Domain Name drop-down list with the complete list of domains supported by the target Java application. From this list, pick the domain that contains the MBeans of your interest.

  • To proceed with the configuration, click the Configure button. Doing so will invoke the NEW MEASURE DETAILS pop up window using which a new measure can be added. In this pop up window, specify the following:

    • The Measure index determines the order in which the measures are to be displayed in the monitor console. For example, if you select 1 as the Measure index then the corresponding measure will appear first in the list of measures displayed in the monitor console. Note that the same Measure index should not be assigned to two different measures of a particular test.

    • The Measure name field indicates the name of the measurement (this will be displayed in the eG monitor interface).

    • The Database column size field indicates the size of each database record corresponding to a measurement value. For example, Number(7,4) indicates that the output of the measurement will be a number in the range 0 to 100, with the fractional value being limited to four decimal places.

    • The Unit (whether %, seconds, requests/sec, etc.) specifies the unit in which the measurement's value is reported. The required unit can be selected from the options available in the list box.

    • In addition to the above, this test type requests the specification of a Process method. By selecting an option from the Process method list box, you can indicate the processing that must be performed on the script / batch file's output before passing the results to the eG agent. The options offered by this list box are:

      • Option Information
      UNALTERED Selecting this option will ensure that no additional information is displayed along with the specified measure in the monitor console. In other words, the Current Value of the measure is displayed.
      PERCENT_INCREASE

      Selecting this option will display the percentage by which the current value of the measure exceeds its previous value (i.e. the value of the measure during the previous test execution). While an increase displays a positive value, a decrease will display a negative value. The formula used is:

      [(Current Value − Previous Value) / Previous Value] * 100

      PERCENT_DECREASE This option will display the percentage by which the current value of the measure falls below its previous value. While a decrease displays a positive value, an increase will display a negative value.

      [(Previous Value − Current Value) / Previous Value] * 100

      PERCENT_CHANGE This displays the percentage change between the current value and the previous value.

      ABS[(Current Value − Previous Value) / Previous Value] * 100

      RATIO This displays the ratio of the current value of the measure over its previous value.

      (Current Value / Previous Value)

      RATE

      This displays the result of the following formula:

      (Current Value − Previous Value) / Time since the last measurement

      DIFFERENCE This displays the absolute value of the difference between the current value and the previous value.

      ABS(Current Value – Previous Value)

      By default, Unaltered is selected as the Process Method.

    • Sometimes, administrators may want to convert the unit of measurement of a performance metric before displaying the same in the eG monitoring console. For instance, a test may extract an ‘MB’ value from the target server as a measure, but while reporting it in the eG monitoring console the administrators may want the unit of the measure to be changed to ‘KB’ instead. Similarly, a duration value originally available in ‘minutes’, may have to be changed to ‘Secs’ before it is displayed in the console. If you want the unit of the measure being added to be so converted at test run time, then select a Conversion Factor from the list. For example, if a value in ‘Bytes’ needs to be converted to ‘MB’, then select /1048576 (Bytes to MB) as the conversion factor. By default, 1 is chosen as the Conversion Factor; this implies that, by default, unit conversion does not take place for a new measure at test run time.

    • The alarm window in the eG monitor interface displays all the currently outstanding alarms. Along with each alarm, the list of tests corresponding to the alarms and a brief description of the problem are displayed. For example, a disk space alarm indicates that the test reporting the problem is DiskTest and the problem description is “High disk utilization {C:}”. The problem description corresponds to the measure - Pct_disk_util- that has violated its thresholds. In this example, the Alarm display string corresponding to the Pct_disk_util measurement is “High disk utilization”. The alarm display string rather than the measurement name is displayed in the alarm window so as to make it easier for IT infrastructure operators to understand and use the eG Enterprise suite. When configuring a measurement for a custom test, specify the text string that must be displayed in the eG alarm window when the corresponding measurement violates its threshold.

    • Since you have already chosen as the Domain name, the eG manager will automatically discover all the MBeans that are available within the chosen domain, and will make them available for selection in the Mbean name list. From this list, choose the MBean that reports the values for the measure that is being added.

      Note:

      Once a Domain is chosen for a test, all the measures of that test should be based on the MBeans and attributes within that domain only.

    • Upon selection of an Mbean name, all the attributes of the chosen Mbean will be automatically discovered and displayed as the options of the Attribute name list. Now, from the Attribute name list, select the Mbean attribute that reports values for the measure being added.

    • By clicking on the Add button, the measurement can be added. Similarly, you can add multiple measurements for a JMX test.

Uploading an MBean File to the eG Manager Host and Using that File to Add a New Measure

To add a new measure by uploading an MBean File to the eG manager, do the following:

  • Select the Upload an MBean File option in from the Measure Selection Options list to upload the file to the eG manager host.

  • Next, specify the full path to the MBeans file that was generated previously in the Path of the file text box. To browse for the file path and upload it, click the Upload button.

  • In the FILE UPLOAD pop up window that appears, click the Browse button to browse for the file path, and then click the Upload button therein to upload the file.

  • If the file is successfully uploaded to the eG manager, then the path to which the file has been uploaded will be displayed in the Path of the file text box.

  • If a valid MBean file has been uploaded, then eG Enterprise will automatically discover the domains from the uploaded file and display the same in the Domain Name list. To proceed with the measure configuration, pick a domain from the list.

    Note:

    If a test reports multiple measures, then the MBeans and/or attribute names mapped to all such measures should belong to the same Domain.

  • Upon clicking the Configure button, NEW MEASURE DETAILS pop up window appears. Refer to MBean Auto Discovery section to know how to add the measure.

Adding a New Measure Using an Existing MBean File

An MBean file may pre-exist in the <EG_MANAGER_INSTALL_DIR>\tmp directory in the eG manager host in the following situations:

  • The MBean file may have been manually copied to the eG manager host;

  • The MBean file may have already been uploaded to the eG manager using the steps mentioned in the Uploading an MBean File to the eG Manager Host and Using that File to Add a New Measure section.

  • The MBean file may have been created using the MgrMbeanDiscovery.bat file (and not the AgentMbeanDiscovery.bat)

To use an existing MBean file to configure a new measure for a JMX test, do the following:

  • Select the Use Existing MBean File option from the Measure Selection Options list. Once this option is chosen, then all the MBean files that pre-exist in the <EG_MANAGER_INSTALL_DIR>\tmp directory in the eG manager host will populate the Path of the file drop-down. From this drop-down, select the file that you want to use for measure configuration.

  • Then, click the Get Domains button to get the domains. eG Enterprise will then automatically discover the domains from the chosen file and display the same in the Domain Name list. Pick a domain and click the Configure button to proceed with the measure configuration.

  • Upon clicking the Configure button, NEW MEASURE DETAILS pop up window appears. Refer to MBean Auto Discovery section to know how to add the measure.

Adding a Measure Using the Manual Entry Method

Use the Manual Entry method if you know the exact domain, Mbean, and attribute that can report the measure you want, and do not wish to needlessly auto-discover MBeans or load them from a file for this purpose.

To manually configure an MBean to add a new measure for a JMX test, do the following:

  • Select the Configure Manually option from the Measure Selection Options list.

  • The NEW MEASURE DETAILS pop up window will then appear. Refer to MBean Auto Discovery section to know how to add the measure using this pop up window.

When a measurement is successfully added, a response page indicating the measurement and its details will appear. Previously added measurements can be deleted using the Delete button that appears below every measurement that is added. Such measurements can also be modified by clicking the Modify button.