This page last changed on Jul 20, 2009 by mmcgarry.

Using JMX MBean Query

Topics marked with * relate to HQ Enterprise-only features.

The JMX MBean Query tool allows you to search for MBeans, display their attributes, and invoke selected MBean operations on them.

When HQ alerts you of availability or health issues with a JVM resource or service, you can use the JMX MBean Query tool to troubleshoot and resolve the problem.

The MBean attributes displayed in the JMX MBean Query tool are read-only; the console does not support attribute editing. In this version of HQ, support for MBean operations is limited to operations with one or no arguments of primitive or simple type.

The JMX MBean Query tool is available on the Views tab when you have a JVM server selected in the HQ portal. These instructions assume that your JVM is in HQ inventory. Note that JVMs are not auto-discovered by HQ. For related instructions, see Configuring Sun JVM for Monitoring.

Entering Query Options

To access specific MBean attributes and operations, you enter search patterns in the these text boxes in the JMX MBean Query tool page:

  • Operation Regex Filter - To restrict the MBean operations returned, enter a valid Java regular expression.

Click the Query MBeans button to execute the search. 

For MBeans whose object name matches the Object Name Pattern, attributes and operations that match your filter criteria will be listed.  For example:

Enabling Automatic Refresh

If you wish the console to periodically refresh the attribute values, select an interval from the Refresh Interval pulldown. 

Defining Saved Mbean Searches

If you expect to perform the same search frequently, you can create an XML file that specifies the search criteria. You name the file according to a predefined convention, and store it in a specific directory in your HQ Server installation. Queries you define in this way will appear in the tool's Preset Searches drop-down menu.

When you run a saved search, the Object Name Pattern, Attribute Regex Filter, and Operation Regex Filter it comprises will be displayed in the corresponding text boxes at the top of the view.

Name the file that contains a saved search like this:

SearchID-filter.xml

All filters defined in this file will then appear in the Preset Searches drop-down menu and will be named according to the filter ID. Save the file in:

$JBOSS_HOME/deploy/hq.ear/hq.war/hqu/jmx/conf

The following topics defines the XML schema for saved MBean searches.

Schema for JMX Search Criteria

A saved MBean search criteria consists of:

  • A top-level filters element, containing at least one filter sub-element. Each filter sub-element consists of:
    • An id attribute containing an identifier for the search. This string will appear in the Preset Searches drop-down menu. Each search you define and save on an HQ server must have a unique d attribute.
    • An objectName sub-element, whose value is the object name pattern used for the MBean query. 
    • An attributeRegex sublement, whose value is the Java regular expression used to filter the attributes returned from the MBean query. 
    • An operationRegex sublement, whose value is the Java regular expression used to filter the operations returned from the MBean query.

For example:

<?xml version="1.0" encoding="UTF-8"?>

<filters>

  <filter id="JVM Memory MBean">
    <objectName>java.lang:type=Memory</objectName>
    <attributeRegex>.*Usage</attributeRegex>
    <operationRegex>.*</operationRegex>
  </filter>

  <filter id="JVM Platform MBeans">
    <objectName>java.lang:*</objectName>
    <attributeRegex>.*</attributeRegex>
    <operationRegex>.*</operationRegex>
  </filter>

</filters>

Importing a Sun JVM into Inventory

Your Sun JVM must be configured for JMX monitoring. For instructions, see Monitoring and Management Using JMX on the Sun web site.

Once your JVM is configured for JMX monitoring, define it as a server in HQ. Browse to the platform where the JVM is located view its monitoring page. Select "New Server" from the "Tools Menu" in the upper right corner. On the next page, name your JVM and select "Sun JVM 1.5" from the drop-down menu. In the "Install Path" field, enter your $JAVA_HOME.

On the subsequent page, click the "Configuration Properties" link, highlighted in yellow. If you've set up password authentication for your JMX monitoring, you'll have to input your user and password here. Double-check the jmx.url field and set the port number accordingly. To track configuration and log files, add in the appropriate info after checking the boxes "server.log_track.enable" and "server.config_track.enable". Make sure the box for "Auto-Discover Garbage Collectors and Memory Pools?" is checked. After clicking ok, HQ Server will start receiving the default metrics for that JVM, although it will take a few minutes for them to appear.

Return to HQ Portal Reference.

jmx console.gif (image/gif)
Document generated by Confluence on Apr 20, 2010 15:01