Monitoring Java Management Extensions (JMX) MBeans

You can define a data source to collect data from JMX MBeans. Data from every monitored MBean is placed into a data set. Depending on the MBean, the data set can produce a single row or multiple rows.

1. On the Agent Initial Data Source page or the Data Source Location page, click Data from a server in the Monitoring Data Categories area.
2. In the Data Sources area, click JMX.
3. Click Next.
4. On the JMX Information page , click Browse to see all of the JMX MBeans on the MBean server.
   After you define the data source, you can use the browse function to pre-populate your attribute list. You can then add to, remove from, or modify the attributes that the browser inserted. The names for these attributes can be long and difficult to type correctly. Using the Browse option is an easy way to input the correct name.

   Note: You can manually create JMX data sources by specifying an Object Name and clicking Next without using the browser. Manually creating JMX data sources creates two data sources. An event data source that contains predefined attributes for JMX notifications is created. Also, a collection data source is defined containing one attribute that you must specify in the wizard.

   MBean pattern

   Shows the MBean pattern.

   Global JMX Options

   Shows the level of support.

   Support is provided for the following JMX servers:

   • Java 5 operating system MBean Server. Connection is made by using the JSR-160 connector. Notifications and monitors are supported.
   • WebSphere® Application Server, version 6 and later. Connectors are provided for both SOAP and RMI protocols. JMX Monitors are not supported because MBeans cannot be created by a remote agent.
   • WebSphere Community Edition and other Apache Geronimo-based application servers. Connection is made through standard JSR-160 connectors. JMX notifications and monitors are supported in versions 1.1 and later.
   • JBoss Application Server, version 4.0 and earlier.
   • JBoss Application Server, JSR-160 connection.
   • WebLogic Server, version 9 and newer. Connector is provided for T3 protocol.

5. The first time that you run the JMX browser, there are no items in the MBean server scroll down menu. To add connections, click the Add) button.
   Use the Edit button to modify or delete the connection that you already defined and selected in the scroll down menu. The connection definitions are stored in the workspace, so that, when you create a connection, it is remembered. Complete the following steps to create a connection. If you already have a connection, skip to the next step.
   1. To create a connection to an MBean Server, click Add to add a connection or to edit an existing connection.
      The Java Management Extensions (JMX) Browser window is shown when no connections are defined.
   2. After you click Add to add a connection, the Select Connection Type page opens.
   3. Use the MBean Server Connection wizard to connect to an MBean server. The new connections that are listed on the page are selections that you can make to create connection. You can use the list of existing connections to create a new connection using an existing connection as a template. Select one of the new connection types and click Next to begin creating a connection.
   4. After you select a connection type, you might be asked to select a more specific type of connection. Two templates that are based on the Standard JMX Connections (JSR-160) connection type are shown. Select the template that is most appropriate for your MBean server and click Next.

      

      The Connection Properties page (Figure 1) contains the details on how to connect to an MBean server. You must complete the page with details about your MBean server.

      Important: If your data source connects to a remote WebSphere Application Server, ensure that WebSphere Application Server is also installed on the host that is running Agent Builder and set theJava location setting to the Java runtime environment that the local WebSphere Application Server uses.
   5. Select the Save the password in the Agent Builder workspace check box if you want to save the password for this connection.
   6. Optional: Select Set as agent configuration defaults if you want the defaults for JMX to be copied from these connection properties.
      For example, in Figure 1 the default JMX base path is C:\jboss-eap-6.3.01\jboss-eap-6.3, the JMX service URL is service:jmx:remoting-jmx://localhost:9999 and the Java location is C:\Program Files\IBM\Java70\jre

      1. After you specify the properties that are required to connect, click Test Connection to ensure that the connection can be established. If the connection is not successful, correct the necessary properties.
      2. When the connection is successful, click Finish to return to the browser that uses the connection you configured.

   The Java class path information in the Connection Properties page contains three fields. These fields must be completed as necessary to connect to an MBean server that requires Java classes that are not included in the Java runtime environment. Normally, the MBean server you want to connect to must be installed on the same system as the Agent Builder. In this case, specify the directory where the application that contains the MBean server was installed as the JMX base paths field. The JMX Jar Directories field then lists the directories relative to the Base Paths directory that contain the JAR files that are required to connect to the MBean server. The JMX class path field can be used to include specific JAR files. The JAR files that are listed in the JMX JAR Directories field are not required to be listed separately in the JMX class path field.

   Any of the fields can contain more than one reference; separate the entries by a semicolon. These values are the same values that are required when you configure the agent. For more information, see (JMX configuration).

6. After you select a connection, the JMX Browser downloads information about the MBeans from the JMX server. This information is shown in the following four areas of the JMX Browser window (Figure 2):

   Directions for screens that begin with Java Management Extensions (JMX) Browser window to Runtime Configuration tab of the Agent Editor: From the JMX Information page, select Browse. From the browser (JMX Browser with no connection-selected), select Add. From the JMX Connection Selection page select JBoss, then select Next. From the JMX Connection Properties page, customize two Connection Properties: JBoss provider URL: jnp://wapwin3.tivlab.raleigh.ibm.com:1099/ and JBoss Jar Directories: The full path to the directory that contains the following JAR files: jbossall-client.jar, jboss-jmx.jar, jboss-jsr77-client.jar, jboss-management.jar. Select Finish. This configuration sets up your JBoss connection so you can get similar screens as shown here.

   

   • MBean Key Properties area: This area is a collection of every unique Object Name key that is found from all the MBeans on the server. The [Domain] entry is special because it is not really a key. However, the [Domain] entry is treated as an implied key for the value of the MBean domain. Select an item from this list, and the MBeans that contain that key property are found. The list of values of the key property are shown in the Selected Key Property Values list. When you check a key property, it is included in the Object Name pattern for the data source.
   • Selected Key Property Values area: This area shows the values of the currently selected MBean Key Property from all MBeans. Selecting one of these values checks the MBean key property. The selection also updates the Object Name Pattern shown in the message field with the MBean key property name and value.
   • A table lists all MBeans matching the Object Name Pattern: As you select Key Properties and Values from the MBean Key Properties and Selected Key Property Values lists, you see the Object Name Pattern update. You also see the list of MBeans in this table change to reflect the list of MBeans that match the pattern you selected. If you have a pattern that is not matching any MBeans, you can clear entries in the MBean Key Properties list. You clear entries by clicking the check box next to a key that is being used by your pattern and removing the check mark. Also, you can manually edit the pattern to find the MBeans you are looking for. The pattern *:* selects all MBeans.

     You can use this table to browse the MBeans from the server and decide which ones contain the data you want to monitor. To help browse a potentially large number of MBeans, you can sort by any key attribute (from the menu or by clicking a column header). You can also show any key attribute in any column by selecting Show Key Property from the menu. When you see a key property value in the table that identifies MBeans you want to monitor, right-click on that value and choose Select only MBeans with Key Property from the menu.

   • A table that contains details for a selected MBean: The JMX Browser shows you information about a single MBean. To see details for an MBean, you select the MBean from the table that shows the list of MBeans matching the current filter. The key information about the MBean is the list of Attributes, Operations, and Notifications it defines.

   To create a data source from the JMX Browser, use the four panels that were described earlier to build an Object Name Pattern. Build the Object Name Pattern to match a set of MBeans that each contains the monitoring data you want to collect. For instance, if you wanted to monitor data from all of the ThreadPool MBeans, use the following steps:

   1. Select type from the MBean Key Properties panel. Selecting type causes the values in the Selected Key Properties Values to be updated to list all unique values from the type key of any MBean.
   2. Select ThreadPool from the list of values for the type key. After you select ThreadPool, the type key property name is selected in the MBean Key Properties panel and the Object Name Pattern is updated to *:type=ThreadPool,*. The list of MBeans is also updated to show only the MBeans that match this pattern.
   3. Select one of the MBeans from the MBean list to see the attributes, operations, and notifications available for the MBean. If your MBean list contains more MBeans than you want to monitor, you must continue this procedure of selecting key properties and values. Continue until you have the Object Name Pattern that identifies the set of MBeans you want to monitor. You can also open a menu in the MBean list to update the Object Pattern with key property values shown in the table.
7. When the object name pattern is correct, select an MBean from the table.
   All attributes of the selected MBean are the initial attributes in the new JMX data source. Some attributes might not contain data. After the JMX data source is created, review the attributes and remove any that are not significant. If the selected MBean has no attributes, you are warned that the data source is created with no attributes. If the selected MBean contains notifications, an Event data source is also created to receive notifications from the MBeans.

   Important: For every MBean attribute, Agent Builder creates an attribute in the new data set. For a numeric MBean attribute, Agent Builder creates a numeric attribute. For any object types, including String, Agent Builder creates a string attribute containing a string representation of the value. If an object from an MBean attribute is of the javax.management.openmbean.CompositeData type, and the Agent Builder browser can read the object itself, it creates several attributes, one for each object embedded in the CompositeData object. To include values internal to an object other than a CompositeData object (fields or method return values), you need to create an attribute that has a more complex metric name, as described in Specific fields for Java Management Extensions (JMX) MBeans.
8. Click Finish in the filled on JMX Information page.
   Data sources are created based on the MBean that was selected in the previous step. If no MBean was selected, an attribute group with no attributes is created. A warning is shown, giving you a chance to select an MBean. The notification data source has the word, Event, at the beginning of the data source name to distinguish it from the data source that shows attributes.
9. To change other JMX options for the agent, click Global JMX Options. With these options, you can:
   1. Choose whether JMX monitors are supported by this agent. If you want JMX monitor attribute groups and Take Action commands to be created, select Include JMX monitor attribute groups and take actions
      See the next section for a description of JMX monitors.
   2. Select the types of MBean servers your agent connects to when it is deployed.
      There are several vendor-specific types of servers that are listed, along with a generic JSR-160-Compliant Server for standards-based servers. You can select as many as needed, but you must select only server types that support the MBeans that are being monitored. You must select at least one. If you select more than one, at agent configuration time you are prompted to specify which type of server you want to connect to.
10. Click OK after you select the wanted option.
11. Optional: You can test this attribute group by clicking Test. For more information about testing, see (Testing JMX attribute groups)
12. Optional: You can create a filter to limit the data that is returned by this attribute group by clicking Advanced. For more information about filtering data from an attribute group, see Filtering attribute groups
13. Click Next.
14. On the Select key attributes page, select key attributes or indicate that this data source produces only one data row. For more information, see (Selecting key attributes).
15. Click Next.

    The JMX Agent-Wide Options window shows the types of application servers that the Agent Builder supports. If you previously selected Set as agent configuration defaults on the Connection Properties page, the type of application server that you browsed to is automatically selected.

16. In the JMX Agent-Wide Options window (Figure 3), select any other types of application servers to which you want your agent to be able to connect.
    Note: In the example shown, choosing JBoss Application Server JSR-160 connection is the same as choosing JSR-160-Compliant Server except that different default values are supplied.

    

17. Do one of the following steps:
    • If you are using the New Agent wizard, click Next.
    • Click Finish to save the data source and open the Agent Editor.
18. If you want to change the types of application servers to which you can connect after the agent is created, click Global JMX Options in the JMX Data Source Information area.
19. In the JMX Agent-Wide Options window, change any selections that you want.
20. Click OK.
21. To view the configuration sections and properties that were automatically generated, click the Runtime Configuration tab of the Agent Editor.

    The default value of the JBoss base paths property has the value that was entered in the JMX browser.