Java Management Extensions (JMX™) technology is rapidly becoming a common, standardized way to provide basic monitoring of Java™/J2EE™ applications and application servers. By equipping applications with components known as MBeans, IT Departments can expose application information (i.e.: availability, downtime, upgrades, performance, sizing, security, integration) and other key metrics to enable the monitoring and control of applications. In addition, many middleware products, such as application servers and business process management tools, are being offered with performance metrics automatically exposed via JMX™.
While many companies have enabled JMX™ for their mission-critical J2EE™ applications, they find they are still unable to effectively manage and monitor them. While some solutions do exist, they lack key functionality such as alerts, real-time analytics, or the ability to deliver information in context by comparing real-time data to historical data. Without these capabilities, companies are unable to provide adequate application management, nor true real-time operational visibility.
With RTView, the JMX™ data source allows you to:
§ browse available MBean attributes and assign their values as input to a variety of graphic objects in web-based dashboards;
§ archive the MBean data in the RTView Historian for trend analysis;
§ aggregate MBean attributes to, for example, provide subtotals over dimensions or time series;
§ define thresholds and actions based on MBean attributes or aggregated data; and
§ create interactive dashboards or automated alert behavior that can manage specific applications with the ability to execute an MBean operation.
This section includes:
§ “System Requirements and Setup - JMX” on page 560
§ “Attach to JMX Data” on page 560
§ “Define JMX Command” on page 566
§ “Substitutions - JMX” on page 568
§ “Application Options - JMX” on page 569
§ “RTView Deployment - JMX” on page 575
§ “Quick Start Tutorial: JMX” on page 577
§ “Sample JMX Application” on page 582
§ “JMX Data Source Command Line Options” on page 584
System Requirements and Setup - JMX
The JMX data source has no additional “System Requirements”.
In addition to general environment variables (see “Setup”), you must include the tools.jar file (from your JDK installation) in “RTV_USERPATH” to utilize the Automatically Discover Local MBean Servers application option and -jmxautodiscover command line option. See “JMX Administration Tab” and “JMS Data Source Command Line Options” for more information.
From the Object Properties window you can access the Attach To JMX Data dialog. This dialog is used to attach an object property to an MBean attribute or operation, giving you the ability to display the results within an RTView display. Once an object property has been attached, it receives continuous updates. By default, each MBean method is executed once each update period, but you can set the default poll interval on the JMX Administration tab in the Application Options dialog.
To bring up the Attach to JMX Data dialog, right-click on the Property Name from the Object Properties window and select Attach to Data>JMX. The Attach to JMX Data dialog provides several drop down menus that allow you to specify information regarding the MBean method to execute. If the drop down menu does not contain the item you require, type your selection into the text field.
|
Field Name |
Description |
|
Connection |
Connection name. Select Tools>Options and click on JMX to define a JMX Connection or JMX Connection Group. See “JMX Connections Tab” and “JMX Connection Groups Tab” for more information. |
|
MBean Name |
Name of the MBean containing the method to execute. |
|
Data Mode |
Poll for Values – Poll for attribute values or execute operations. If this option is selected, you can control how often the data is polled in the Update Mode field. Listen for Notifications – Register as a listener for attribute notification events. When this option is selected, initial data is polled for the attribute and then data is only updated when notification events are received. |
|
Attribute(s)/Operation(s) |
Name of the attribute or operation to execute. If the attribute or operation you select requires arguments, then the dialog will populate with a text field for each argument. The values entered in these argument fields are not validated. Values listed populate based on the selected MBean and Data Mode. If Data Mode selected is Poll for Values, all available attributes and operations that return data will be listed. Otherwise if Data Mode selected is Listen for Notifications, only attributes returned by the MBean getNotificationInfo() method will be listed. |
|
Field(s) |
Name of the items to display from the selected attribute or operation. This field is not required if a single simple attribute is selected from Attribute(s)/Operation(s). |
|
Filter |
Select this check box to filter the MBean method result. |
|
Filter Field Name |
MBean method field to use as filter. |
|
Filter Field Value |
Value that the filter field must equal. Enter * to display all rows in the table. Enter "*" to use * as a literal comparative value. To list multiple values, separate with a semicolon. For example: value1;value2;value3. If your value contains a semicolon, enclose it in single quotes. |
|
Update Mode |
If Data Mode selected is Poll for Values, the following options are available: Poll Once - Poll for data only once. Select if the data returned by this attribute or operation is static. Poll Every Default Poll Interval - Poll for data each Default Poll Interval. See “Application Options - JMX” for information on setting the Default Poll Interval. This is the default Update Mode. Poll Every Poll Interval - Poll for data each Poll Interval. If this option is selected, you must specify a Poll Interval. Poll On Demand - Poll for data each time a display that uses the data attachment is opened and each time a substitution string that appears in the data attachment has changed. |
|
Poll Interval |
Enter the time (in seconds) to poll for data. This option is only available if the Update Mode selected is Poll Every Poll Interval. Note: Because the Poll Interval is superseded by the General Update Period, the amount of time elapsed between MBean polls may be longer than the value entered. For example, if the General Update Period is 2 seconds and the Poll Interval is 5 seconds, MBean attributes and operations will be polled every six seconds. See “General Tab” for more information. |
|
Data Server |
Select to read data through your configured Data Server and not directly from the JMX data source. Default - Select the default Data Server you configured in Application Options>“Data Server Tab”. None - Bypass data being redirected through the specified data server(s) for this attachment and instead attach directly to the data source. Named Data Servers - Select a Named Data Server that you configured in Application Options>“Data Server Tab”. Multi-Server Attachment - To configure multiple data servers, enter a semicolon (;) delimited list containing two or more Named Data Servers (e.g. ds101;ds102). Each name specified must correspond with a Named Data Server that you configured in Application Options>“Data Server Tab”. It is also possible to specify __default and __none (e.g. __default;ds101;ds102). Note: The values __default and __none begin with two underscore characters. |
|
|
Alternatively, a value of * can be entered to specify all data servers, including __default and __none. When multiple data servers are specified, the data attachment will be directed to each data server in the list. For tabular data attachments, a column named DataServerName will be added as the first column of the table and contain the name of the server from which the data was received. |
|
|
A multi-server attachment will receive data independently from each of the servers it specifies, so in most cases it will be necessary to combine the tables received into a single table. This can be accomplished in two ways: |
|
|
1. The multi-server attachment can be applied to a local cache that has the DataServerName column specified as an index column. The current table of that cache will contain the combination of the tables received from all servers. Note: It may also be necessary to configure cache row expiration settings to remove defunct rows. 2. The multi-server attachment can be applied as the Table argument of the RTView function named Combine Multi-Server Tables. See “Tabular Functions” for more information. |
Drop down menus populate based on connections added in the Application Options window.
When an object property has been attached to data, the Property Name and Value in the Object Properties window will be displayed in green. This indicates that editing values from the Object Properties window is no longer possible. To remove the data attachment and resume editing capabilities in the Object Properties window, right-click on the Property Name and select Detach from Data. You will recognize that an object property has been detached from the data source when the Property Name and Value are no longer green.
Fields in the dialog change colors according to the information entered. These colors indicate whether or not information is valid. Information is validated against the connections added in Application Options window.
Note: If the Connection is *, the MBean field is validated against the first active connection. If the MBean name uses * for a key property, the Attribute(s)/Operation(s) field is validated against the first MBean found matching the name.
Note: The Filter Field Value field and argument fields related to selected Attribute(s)/Operation(s) are not validated.
The following describes the significance of the validation colors:
|
Blue |
Unknown Entry |
Entry is not recognized. When a Connection is unknown, the MBean, Attribute(s)/Operation(s), Field(s), Filter Field Name, and Filter Field Value are also unknown. |
|
Yellow |
Offline |
Connection is offline. |
|
White |
Valid state |
Entry is valid. |
|
Red |
Invalid state |
Entry is not valid. |
|
Grey |
Not Required |
Field does not require a value. This applies to Field(s) if the selected attribute or operation returns a single simple field. |
The Substitutions feature allows you to build open-ended displays in which data attachments depend on values defined at the time the display is run. A generic connection such as $conn is used instead of a specific connection. Later when the display is running, this generic value is defined by the actual name of a specific connection, such as samplejmxapp. In this way, a single display can be reused to show data from a number of different sources. Substitutions can be used in any field in this dialog. For more information on creating displays using substitution values, see “Substitutions”.
The JMX data adapter provides an MBean called RTViewDs:type=Connection, which provides a table containing JMX connection information. In the Attach to JMX Data dialog, select RTViewDs:type=Connection from the MBean Name drop-down menu.
|
RTViewDs Table Name |
Column Available |
Description |
|
Connection |
Connection |
Name of the JMX Connection for the data attachment. |
|
Host |
JMX MBean Server host name. This field is available if it was used to create the connection (the Enter URL option in the Add JMX Connection dialog was NOT enabled when the JMX connection was created). See “JMX Connections Tab” for more information. |
|
|
Port |
Port number for the JMX MBean Server. This field is available if it was used to create the connection (the Enter URL option in the Add JMX Connection dialog was NOT enabled when the JMX connection was created). See “JMX Connections Tab” for more information. |
|
|
URL |
URL of the JMX MBean Server. This field is available if it was used to create the connection (the Enter URL option in the Add JMX Connection dialog was enabled when the JMX connection was created).See “JMX Connections Tab” for more information. |
|
|
Connected |
True if the connection is connected. |
|
|
Display Name |
Display name of the connection. Used when Auto Discover is true and is the name of the discovered connection. |
The following special values can be entered.
|
Connection |
* |
All connections are displayed. A Connection attribute is added to the Attribute(s)/Operation(s) list. This attribute displays the name of the connection. |
|
MBean Name |
* |
One * can be used in the domain of the MBean name in order to display MBeans with similar names. When * is used in the domain, a Domain column containing the domain name is added to the Attribute(s)/Operation(s) list. For example, a connection has the following domains: SampleJmxAgent1 SampleJmxAgent2 MyAgent You could specify * to get all three or SampleJmxAgent* to get the first two. However, you could not specify *Agent* because only one * is allowed. A * can be used for any key property in the MBean name. When * is used, an attribute named for that key property is added to the Attribute(s)/Operation(s) list. For example, a connection has the following MBeans: Catalina:type=Manager,path=/,host=localhost Catalina:type=Manager,path=/demoapps,host=localhost Catalina:type=Manager,path=/productionapps,host=otherhost |
|
You can specify either of the following for the MBean Name in your data attachment: Catalina:type=Manager,*,host=localhost or Catalina:type=Manager,* An attribute will be added to the Attribute(s)/Operation(s) list for each key property following the *. In both examples above, a path and host attribute will be added to the Attribute(s)/Operation(s) list. Since the first example lists host=localhost, the data attachment will return a two row table, the first row showing the information for path=/ and the second row showing the information for path=/demoapps. The host for the MBean with the path=/productionapps is not localhost, so it will not be included in the returned table. The second example lists * for both path and host, so the data attachment will return a three row table, the first row showing the information for path=/, host=localhost, the second row showing the information for path=/demoapps, host=localhost and the third row showing the information for path=/productionapps, host=otherhost. |
||
|
Attribute(s)/Operation(s) |
* |
All attributes and operations for the selected MBean method are displayed. Note: <TABULAR> will be displayed in cells for MBean methods that return tabular data. The way composite attributes will be displayed depends on the Expand Composite Attributes setting in Application Options. See “JMX Administration Tab” for more information. |
Select Multiple Attributes/Operations or Attribute Fields (Tables Only)
From the Attach to JMX Data dialog you can select multiple attributes or operations to display or, for a single attribute or operation, you can specify which items to display as columns in a table and in what order they will appear. In order to populate the Attribute(s)/Operation(s) list, you must first select a valid MBean Name. In order to populate the Field(s) list, you must first select a valid entry in the Attribute(s)/Operation(s) field.
Note: When specifying multiple attributes or operations, you can only select MBean methods that return simple single values or MBean methods that return composite data. The way composite attributes are displayed in a table with other attributes depends on the Expand Composite Attributes setting in Application Options. See “JMX Administration Tab” for more information.
Click on the ellipsis button or right-click in the Attribute(s)/Operation(s) or Field(s) fields and choose Select Columns to display the Select Columns dialog. The dialog should contain a list of Available Columns that you can add to your table.
To add a field, select an item from the Available Columns list and click on the Add button. If the item you require is not listed, type your selection into the Enter Column Name field. Click the Remove button to delete an item previously added to the Selected Columns list. You can control the order of fields in a table by arranging the items in the Selected Columns list with the Move Up and Move Down buttons.
Validation colors indicate whether selected message fields are valid. However, if even one field selected is invalid the field in the Attach to JMX Data dialog registers as an invalid entry.
If no data is available for a table row within a selected column, the table cell displays one of the following values: N/A, false, 0, or 0.0.
The following describes Attach to JMX Data dialog commands:
|
Command |
Description |
|
OK |
Applies values and closes the dialog. |
|
Apply |
Applies values without closing the dialog. |
|
Reset |
Resets all fields to last values applied. |
|
Clear |
Clears all fields. Detaches object from data source (once Apply or OK is selected). |
|
Cancel |
Closes the dialog with last values applied. |
Note: The JMX data source may not be licensed in your RTView installation.
You can access the Define JMX Command dialog from the Object Properties window. This dialog is used to assign an MBean operation to an object's command property, giving you the ability to execute an MBean operation from within an RTView display. If you execute a JMX command from a Thin Client with Direct Data Connection or any Served Data deployment, the command will execute on the server. If your command fails on a Direct Data deployment, an error dialog will popup with information on why the command failed. In other deployments, the error is only output to the console.
To open the Define JMX Command dialog, right-click on the appropriate command property in the Object Properties window and select Define Command>JMX. See the “Define/Execute Command” section for information on how to execute a command.
|
Field Name |
Description |
|
Connection |
Connection name. You may define a connection on the “JMX Connections Tab” of the Application Options dialog. The “JMX Connection Groups Tab” allows you to define Connection Groups and add them to the drop down menu in the Define Command dialog. |
|
MBean Name |
Name of the MBean containing the operation you want to execute. |
|
Method Name |
Name of the operation you want to execute. |
|
Method Argument(s) |
Method argument fields populate based on which MBean Name and Method Name are selected. To attach a method argument to data, right-click and choose Attach to Data or double-click in the field. |
|
Data Server |
Select to read data through your configured Data Server and not directly from the JMX data source. Default - Select the default Data Server you configured in Application Options>“Data Server Tab” None - Bypass data being redirected through the specified data server(s) for this attachment and instead attach directly to the data source. Named Data Servers - Select a Named Data Server that you configured in Application Options>“Data Server Tab”. Multi-Server Command - When multiple data servers are specified, the command will be executed on each data server in the list. To configure multiple data servers, enter a semicolon (;) delimited list containing two or more Named Data Servers (e.g. ds101;ds102). Each name specified must correspond with a Named Data Server that you configured in Application Options>“Data Server Tab”. It is also possible to specify __default and __none (e.g. __default;ds101;ds102). Note: The values __default and __none begin with two underscore characters. Alternatively, a value of * can be entered to specify all data servers, including __default and __none. |
Drop down menus populate based on connections added in the Application Options dialog. Once a method is selected, argument fields are added to the dialog based on the selected method. See “Application Options - JMX” for more information.
The Substitutions feature allows you to build open-ended displays in which commands depend on values defined at the time the display is run. A generic connection such as $conn is used instead of a specific connection. Later when the display is running, this generic value is defined by the actual name of a specific connection, such as samplejmxapp. In this way, a single display can be reused to send a number of different messages. Substitutions can be used in any field in this dialog. For more information on creating displays using substitution values, see “Substitutions”.
|
$value |
When an actionCommand is executed $value is replaced with the value from the control. This value may be used in any field in the Define JMX Command dialog. Note: This value may only be used for Action Commands. See “Define/Execute Command” for more information. |
The following describes Define JMX Command dialog commands:
|
Command |
Description |
|
OK |
Applies values and closes the dialog. |
|
Apply |
Applies values without closing the dialog. |
|
Reset |
Resets all fields to last values applied. |
|
Clear |
Clears all fields. Detaches object from assigned message subject (once Apply or OK is selected). |
|
Cancel |
Closes the dialog with last values applied. |
In addition to standard built-in substitutions, this data source also sets the following drill down substitutions:
|
Substitution Value |
Definition |
|
$conn |
Connection name from the selected row or object. |
|
$mbean |
MBean name from the selected row or object. |
|
$rowindex |
Row index from the selected row or object. |
|
$filterfield |
Filter field name from the selected row or object. |
|
$filtervalue |
Filter field value from the selected row or object. |
See “Drill Down Substitutions” for more information.
To access the Application Options dialog, in the Display Builder select Tools>Options. There are three Application Options tabs for JMX: “JMX Administration Tab”, “JMX Connections Tab”, and “JMX Connection Groups Tab”.
Options specified in JMX tabs can be saved in an initialization file (JMXOPTIONS.ini). On startup, the initialization file is read by the Display Builder, Display Viewer, Display Server, Data Server and Historian to set initial values. If no directory has been specified for your initialization files and JMXOPTIONS.ini is not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “RTV_JAVAOPTS” for more information.
Note: Options specified using command line arguments will override values set in initialization files. See “JMX Data Source Command Line Options” for more information.
|
Field Name |
Description |
|
Expand Composite Attributes |
Select this option so that you display one column for each item when a composite attribute is displayed in a table with other attributes. The column name will be compositename.itemname. |
|
Default Poll Interval |
Enter the time in milliseconds to control how often MBean attributes are polled or operations in data attachments are executed if no Poll Interval is specified in the data attachment. Default is 0, which polls MBean attributes and operations according to the General Update Period specified in Application Options on the “General Tab”. Because the Default Poll Interval is superseded by the General Update Period, the amount of time elapsed between MBean polls may be longer than the value entered. For example, if the General Update Period is 2000 milliseconds and the Default Poll Interval is 5000 milliseconds, MBean attributes and operations will be polled every six seconds. |
|
Automatically Discover Local MBean Servers |
If selected, RTView will get the list of local MBean Servers once each poll interval. Note: Poll interval is determined by either the Default Poll Interval or according to the General Update Period specified in Application Options on the “General Tab”. All new servers that are discovered are added as connections using the process ID for the connection name. Connections to servers that have exited will be removed. Auto-discovered connections are not saved to JMXOPTIONS.ini. All auto-discovered connections are added to a JMX Connection Group named RTViewDs-Auto. This group cannot be removed or edited and is not saved to JMXOPTIONS.ini. Note: This option requires JDK 1.6 and you must include the tools.jar file (from your JDK installation) in “RTV_USERPATH”. |
|
Auto-Discover Filter |
Filter auto-discovered connections. The filter can be a single value or a ; (semicolon) delimited list of values. For example, com.sl;org.apache would limit auto-discovered connections to those that start with com.sl or org.apache. |
|
Use Multiple Threads for Commands and Polled Queries |
Select to enable multiple threads for commands and polled queries. This option enhances performance in the case where some JMX servers are slow, thus preventing a single server (or servers) from delaying updates from all JMX servers. Note: RTView will create one thread per connection, so this is not a practical option for cases where hundreds of connections are defined. When multiple threads are enabled, the thread that created the JMX connection will be used for all commands and polled queries on that connection. The polled queries will initiate based on the Poll Interval for the data attachment and each connection will update their listeners asynchronously when data becomes available. |
|
|
If multiple threads are disabled, the polled queries are executed synchronously and the listener is not updated until the data from all connections in the data attachment has returned. For example, a data attachment for a table has * in the Connection field and there are five defined JMX connections: § If multiple threads are disabled, then RTView (every Update Period or Poll Interval) will synchronously query all five JMX connections and then update the listener once with a table containing the data for all five connections. When multiple threads are enabled, then RTView (every Update Period or Poll Interval) will asynchronously initiate queries on all five JMX connections. As each query returns data, the listener will be updated with data for that connection. Therefore, the table will be updated five times per Update Period or Poll Interval with each update only containing the data for one connection. |
|
|
Due to the difference in how listeners are updated, users need to confirm that the listeners for their JMX data attachments to multiple connections can handle partial updates. For example: § If you want to see all connections in a single table, you must cache the data. The indexColumnNames property on the cache must be configured correctly. § For existing caches attached to JMX data that want to use this feature, users should confirm that the indexColumnNames property is properly configured. Since the previous behavior wrote all of the JMX data on every update, a cache could have previously worked correctly even if the indexColumnNames property was not configured correctly. When multiple threads are enabled, this will no longer be the case. |
|
|
For existing functions attached to JMX, users must confirm that the function will operate as expected when receiving update containing only one connection at a time. For example, a Join function attached to JMX might assume that all connections are present in every update. If your function requires all of the connections in each update in order to operate correctly, first put the JMX data into a cache and then use the cache as input to the function. |
This tab allows you to add or remove connections and set your default connection.
When you add a JMX connection to the list it will be highlighted in yellow indicating that RTView has not connected to it. To attempt to connect to a JMX connection, click OK, Apply, or Save. If the background remains yellow, then RTView was unable make a connection. Check that your JMX connection was setup correctly and that the JMX instrumented application is running.
Note: Regardless of which tab you are currently working from in the Application Options dialog, each time you click OK, Apply, or Save RTView will attempt to connect to all unconnected connections.
|
Field Name |
Description |
|
Default Connection |
Name of connection used as the default for data attachments. Select from drop down menu to change default setting. |
|
Add Connection |
Click to open the Add JMX Connection dialog. To edit an existing connection, double-click on a selection from the JMX Connections list. 
|
|
|
Connection Name -- Name to use when referencing this JMX connection in your data attachments. |
|
|
Host or IP -- Host name or IP address of the MBean server. |
|
|
Port -- Port that your JMX instrumented application is using to expose MBean methods. |
|
|
Enter URL -- Select to enter the URL (below) that should be used to create this connection. Otherwise, the Host/IP and Port specified will be used to construct a URL for this connection. |
|
|
URL -- URL that should be used to create this connection. Select Enter URL to enable this field. Enter local to make a local connection to an in-process MBean server. |
|
|
Use Client Credentials -- If selected, the User Name and Password from the RTView login will be used instead of the User Name and Password entered in the Add JMX Connection dialog. Connections to this database will only be made when you are running with login enabled. See “Login” for more information. If you will be using the Data Server or the Display Server with a JMX connection that has this option enabled, you must enable Use Client Credentials for Database Login in these applications. In both of these deployments, a connection will be made for each client login, as the users log in. Once all of the clients for a login have closed, the connection for that login is removed. See “Running the Data Server” and “Thin Client Browser with Direct Data - Manual Setup” for more information. |
|
|
User Name -- User name to use when creating this connection. This parameter is optional. |
|
|
Password -- Password to use when creating this connection. This parameter is optional. If you need to provide an encrypted password (rather than expose server password names in a clear text file), use the encode_string command line option with the following syntax: encode_string type mypassword where type is the key for the data source and mypassword is your plain text password. Note: The type argument is only required when you encrypt a string for a data source. For example, enter the following in an initialized command window (see “Initializing a Command Prompt or Terminal Window”): encode_string jmx mypassword and you will receive an encrypted password: encrypted value: 013430135501346013310134901353013450134801334 Copy the encrypted value, paste it into the password field and click Save to save this value to the initialization (*.ini) file. Or, if necessary, manually edit the (*.ini) file to include the encrypted value. Note: If you need to manually edit a configuration (*.ini) file, contact SL Technical Support at support@sl.com for information about supported syntax. |
|
|
Additional Properties -- Add any properties necessary to initiate connections with specific MBean servers. Property Name -- Enter a property name. To specify an encrypted password, use SL. as a prefix in the Property Name. For example: SL.yourpropertyname Property Value -- Enter a property value. To specify an encrypted password, execute the encode_string command line option (above) and paste the encrypted value here. Add Property -- Once you have entered a Property Name and Property Value and click Add Property to insert. Remove Property -- Select a Property Name from the list and click Remove Property to delete. |
|
Remove Connection |
Select a connection from the list and click Remove Connection to delete. |
|
Remove All Connections |
Removes all connections. |
Connecting to Multiple Secure WebSphere Servers
If you need to connect to multiple secure WebSphere servers, you can create a JMX connection to a WebSphere server that, during setup, allows you to add the following WebSphere properties:
com.ibm.CORBA.ConfigURL (required)
com.ibm.SOAP.ConfigURL (optional)
com.ibm.SSL.ConfigURL (required)
These properties point to WebSphere properties files that can be used, among other things, to connect to other WebSphere servers.
To create the connection:
1. Navigate to Application Options> JMX> JMX Connections tab> Add Connection.
The Add JMX Connection dialog displays.
2. In the Add JMX Connection dialog:
a. Enter Connection Name, Host or IP, and Port
b. Enter Client Credentials (User Name and Password)
c. Specify each Property Name and Property Value and click the Add Property button after defining each.
d. Click OK.
3. Click Save on the Application Options dialog to save your changes.
The changes are saved to the JMXOPTIONS.ini file:
jmxconn WebSpheretestConnection localhost 8080 URL:- WebSpheretester 01321012990131701350013350134901350013350134801283 false
com.ibm.CORBA.ConfigURL file:W:/IBM_DEV/WebSphere/AppServer/profiles/AppSrv01/properties/sas.client.props
com.ibm.SOAP.ConfigURL file:W:/IBM_DEV/WebSphere/AppServer/profiles/AppSrv01/properties/soap.client.props
com.ibm.SSL.ConfigURL file:W:/IBM_DEV/WebSphere/AppServer/profiles/AppSrv01/properties/ssl.client.props
jmxdefaultconn WebSpheretestConnection
jmx_mbeans_change_dynamically true
4. To run the instances defined in the property files simultaneously, you need to set the jmx_use_multiple_threads property to true. You can accomplish this in one of three different ways:
a. Specify the property on the command line when starting the dataserver:
run_dataserver -jmx_use_multiple_threads
b. Add the property to the sample.properties file:
jmx_use_multiple_threads=true
c. Add the property to the JMXOPTIONS.ini file:
jmxconn WebSpheretestConnection localhost 8080 URL:- WebSpheretester 01321012990131701350013350134901350013350134801283 false
com.ibm.CORBA.ConfigURL file:W:/IBM_DEV/WebSphere/AppServer/profiles/AppSrv01/properties/sas.client.props
com.ibm.SOAP.ConfigURL file:W:/IBM_DEV/WebSphere/AppServer/profiles/AppSrv01/properties/soap.client.props
com.ibm.SSL.ConfigURL file:W:/IBM_DEV/WebSphere/AppServer/profiles/AppSrv01/properties/ssl.client.props
jmxdefaultconn WebSpheretestConnection
jmx_mbeans_change_dynamically true
jmx_use_multiple_threads true
|
Field Name |
Description |
|
JMX Connection Group Name |
Enter a JMX Connection Group Name and click Add to insert. Once you have added a group, double-click on the name of that group to define its connections in the Select Connections dialog. Note: It is possible to enter a Connection Name that contains one or more wildcard (i.e. *) characters. For example, rtvdisplay* or *jmx*. |
|
JMX Connection Groups |
Select a group from the list and click Remove to delete. |
This page contains details about the deployment process that are specific to your data source. Please go to the Deployment section of this documentation for instructions on how to implement your RTView deployment option. Return to this page whenever you are instructed to refer to deployment information that is specific to your data source.
The JMX data source has no additional requirements.
Data Source Configuration File
RTView saves general application settings as well as data source configuration options in initialization files that are read at startup. If no directory has been specified for your initialization files and files are not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “Application Options”, “Application Options - JMX”, and “RTV_JAVAOPTS” for more information.
Include the following initialization file when you deploy RTView with this data source:
|
File Name |
Description |
|
JMXOPTIONS.ini |
Contains data source options for JMX. |
Note: Options specified using command line and applet parameters override values set in these initialization files.
Rich Client Browser Deployment Setup for Direct Data Connection
This deployment is not supported by your data source. Use the Data Server to supply data to displays with JMX data attachments. See “Rich Client Browser with Served Data” for more information.
Except where noted, all demos can be run in three ways, as an application, or via rich or thin client in a browser.
Rich Client and Thin Client Demos only.
There are rich and thin client demos already installed on the “RTView Demo Server”.
In an initialized command window (see “Initializing a Command Prompt or Terminal Window”):
Type run_startup_demoserver
The Data Source Demo is designed to illustrate each data source.
1. Start the Simulators
Start the simulators for each data source you will be using. To run the “Sample JMX Application”:
In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory and:
type run_samplejmxapp
2. Run Demos - Application, Rich Client Browser, or Thin Client Browser
Application Demo
1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.
2. To view the demo, type:
run_viewer
3. To edit the demo, type:
run_builder
Rich Client Browser Demo
“Start the Demo Server” if it is not running.
1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.
2. Start the Data Server by typing:
run_dataserver -socket
3. In the Data Server dialog, select:
Start Serving Data
4. Open a browser and navigate to http://localhost:8068/dstutorial_applet.
Thin Client Browser Demo
“Start the Demo Server” if it is not running.
1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.
2. Start the Display Server by typing:
run_displayserver
3. Open a browser and navigate to http://localhost:8068/dstutorial.
2. Run Demos - Application, Rich Client Browser, or Thin Client Browser
Application Demo
1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/jmxmonitor directory.
2. To view the demo, type:
run_viewer
3. To edit the demo, type:
run_builder
Rich Client Browser Demo
“Start the Demo Server” if it is not running.
1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.
2. Start the Data Server by typing:
run_dataserver -socket
3. In the Data Server dialog, select:
Start Serving Data
4. Open a browser and navigate to http://localhost:8068/dstutorial_applet.
Thin Client Browser Demo
“Start the Demo Server” if it is not running.
1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/jmxmonitor directory.
2. Start the Display Server by typing:
run_displayserver
3. Open a browser and navigate to http://localhost:8068/jmxmonitor.
This Quick Start Tutorial provides you with the fundamentals on how to use RTView with a JMX Application. Once completed, you can swiftly apply this knowledge to building your own real-time dashboard displays for visual access to your JMX data.
Learn to:
§ Animate graphic objects with JMX data
§ Create a drill down display with JMX data
§ Execute a JMX command
Note: The JMX data source may not be licensed in your RTView installation.
This tutorial requires the following:
§ Register for a license key. If you have not, you must do so before continuing. See “Registration” for more information.
§ “Quick Start Tutorial” - This tutorial requires that you have a working knowledge of RTView. We recommend that you complete the Quick Start Tutorial before continuing.
Start the Sample JMX Application
In this exercise you start the sample JMX application which is the data source used in this tutorial. The sample JMX application is a JMX instrumented application that you can use to animate objects in the Display Builder and Display Viewer.
1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), start the sample JMX application:
Type run_samplejmxapp &
The sample JMX application runs as a background process.
Note: You must follow this initialization process for each new terminal window you open. See the “Setup” section for more details about setting up your environment.
Start the Display Builder
If you are already logged onto the Display Builder, skip this section and go to the Create a Display section, below.
1. In an initialized terminal window (see “Initializing a Command Prompt or Terminal Window”):
type run_builder
2. Login to the Display Builder. By default, the Display Builder does not require a login. Login can be enabled at setup to support “Role-based Security”. The default user name and password are:
User Name: admin
Password: admin
Note: It is possible that your system administrator may have configured another user name and password. In this case, you may also need to select a role.
You are now ready to create a display using the data source.
At this point you have:
§ Registered for a license key. See “Registration” for more information.
• Started the sample JMX application
• Logged on to the Display Builder
• Completed the “Quick Start Tutorial”
In this tutorial you use the sample JMX application as a data source to create a Color Data table that has two columns, one that lists hawk names and the other that lists their color status, as shown below. You will also create an Add Hawk button that adds another hawk to the sample JMX application which is then reflected in the Color Data table.
As you saw in the Quick Start Tutorial, the data structure of tables and graphs (tabular data) enables RTView to automatically create several data source specific, built-in Substitutions for you. You will see these built-in Substitutions used in the target display when you create the drill down. For more information on Substitutions, see “Substitutions”.
In this exercise, you create a drill down using the previously created display, jmx_dd_qs.rtv, as the target display. First you will set the Color Data table to display two columns of data: the device name and the color. Then you will create a drill down that opens a bar graph that shows more detailed data for each device.
Setup Your JMX Connection
Setting up the JMX connection makes the data source available for animating graphic objects in your display.
1. In the Display Builder, select Tools>Options to open the Application Options dialog. See “Application Options - JMX” for more information.
2. Select the JMX Connections tab and click on Add Connection to open the Add Connection dialog.
3. In the Add Connection dialog:
Connection Name - Enter samplejmxapp
Host or IP - Enter localhost.
Port - Enter 9995. This is the port that the sample JMX application uses to expose its MBean methods.
4. Click OK.
5. Click OK to apply and close the Application Options dialog.
The samplejmxapp connection is now available for animating graphic objects in your display.
Display Data in a Table
In this exercise you add a table and then display data in the table by attaching it to the data source.
1. Click on the Add Table 
button and click again in the Working Area to place the table.
2. In the Object Properties dialog:
label (category: Label) - Change the name of the label to Color Data.
autoResizeFlag (category: Column) - Click to select the check box.
valueTable (category: Data) - Right-click in the Property Name field and select Attach to Data>JMX.
3. In the Attach to JMX Data dialog:
Connection - Select samplejmxapp.
MBean Name - Select SampleJmxApp:name=Manager.
Method(s)/Attributes(s) - Select AllData.
Field(s) - Click on the 
button to open the Select Columns dialog.
4. In the Select Columns dialog:
Select Name in the Available Columns list and click Add.
Select Color in the Available Columns list and click Add.
5. Click OK to close the Select Columns dialog.
6. Click OK to apply these values and close the Attach to JMX Data dialog.
The first hawk from samplejmxapp is displayed in the Color Data table. You now need to create a button that adds other hawks.
Create a Button that Executes a Command
In this exercise you create a button that adds additional hawks to the sample JMX application. You do this by adding the button object and defining it with a command. In this case, the command is addHawk.
1. Click the Add Rectangle Label 
button and click again in the Working Area to add a label to the display.
2. In the Object Properties dialog:
command (category: Interaction) - Right-click in the Property Name field and select Define Command>JMX.
3. In the “Define JMX Command” dialog:
Connection - Select samplejmxapp.
MBean Name - Select SampleJmxApp:name=Manager.
Method(s)/Attributes(s) - Select addHawk.
4. Click OK.
5. In the Object Properties dialog:
label (category: Label) - Change to Add Hawk.
6. Double-click on the Add Hawk label. A new hawk appears in the sample JMX application.
7. Double-click again on the Add Hawk button. Each time you double-click the button another hawk is added to the sample JMX application.
Another hawk is then reflected in the table.
You are now ready to setup the drill down.
Create a Drill Down Target in the Table
In this exercise, you create the drill down using the previously created display, jmx_dd_qs.rtv, as the target.
1. Select the Color Data table.
2. In the Object Properties dialog:
drillDownTarget (category: Interaction) - Double-click in the Property Name field to bring up the Drill Down Properties dialog.
3. In the “Drill Down Properties” dialog:
Apply Drill Down To - Select Named Window from the drop down menu. This option lets you re-use the window when you drill down multiple times.
Window Name - Enter jmx. This name should be unique unless the display is to open in an existing window.
Drill Down Display Name - Select dstutorial\jmx_dd_qs.rtv from the drop down menu.
4. Click OK to attach the drill down target and close the dialog.
View the Drill Down Display
In this exercise, you drill down to the target display.
1. Double-click on any cell in the table to drill down to detailed data. The target display opens.
2. Double-click on another cell in the table and the same display is used to show different data based on the row you select.
3. Close the drill down window.
4. In the Display Builder select File>Save.
Go to the main “Quick Start Tutorial”
A sample JMX Application is provided to enable customers to see how to monitor or execute commands on a JMX Application without using their environment. This application uses the generally accepted conventions for MBean architecture. It contains an agent that registers the MBean with the MBean server, an MBean interface that refines all of the methods, and a manager bean which implements all of the MBean methods. The sample JMX Application contains multiple MBeans as described below. All attributes can be queried and are also sent as notifications. Because the hawks are constantly moving, the location attribute notifications are not sent by default. They can be enabled using -notifyMovements: command line argument, specifying the number of milliseconds between notifications. For example -notifyMovements:5000 will send notifications every 5 seconds.
The sample JMX application contains one MBean named SampleJmxApp:name=Manager with the following methods:
|
Method/Attribute |
Type |
Description |
|
AllData |
TabularData |
One row for each hawk, containing the angle, color and name of the hawk. |
|
AllHawkFlapMode |
boolean[] |
Flap mode of each hawk (true = flap, false = soar). |
|
AllHawkPos |
TabularData |
One row for each hawk, containing the flap mode, name, X and Y of the hawk. |
|
AllHawkX |
double[] |
X location of each hawk. |
|
AllHawkY |
float[] |
Y location of each hawk. |
|
Angle |
int |
Angle of the selected hawk. |
|
AngleList |
int[] |
List of all possible hawk angles. |
|
Color |
String |
Color of the selected hawk. |
|
ColorList |
String[] |
List of all possible hawk colors. |
|
HawkPos |
CompositeData |
Flap mode, X and Y location of the selected hawk. |
|
HawkX |
double |
X location of the selected hawk. |
|
HawkY |
float |
Y location of the selected hawk. |
|
Name |
String |
Name of the selected hawk. |
|
SelectedData |
CompositeData |
Angle, color and name of the selected hawk. |
The SampleJmxApp:name=Manager MBean also supports the following commands:
|
Method/Attribute |
Description |
|
accelerate |
Accelerates all hawks. |
|
addHawk |
Adds a hawk. |
|
causeException |
Throws exception. |
|
decelerate |
Decelerates all hawks. |
|
deleteHawk |
Deletes the selected hawk. |
|
resume |
Resumes animation of all hawks (after suspend). |
|
setAngle |
Sets the angle of the selected hawk. |
|
setColor |
Sets the color of the selected hawk. |
|
setName |
Sets the name of the selected hawk. |
|
suspend |
Suspends animation of all hawks. |
An additional MBean is created for each hawk, named SampleJmxHawk_hawkName with the following attributes:
|
Method/Attribute |
Type |
Description |
|
AllData |
TabularData |
One row, containing the angle, color and name of the hawk. |
|
Angle |
int |
Angle of the hawk. |
|
Color |
String |
Color of the hawk. |
|
HawkX |
double |
X location of the hawk. |
|
HawkY |
float |
Y location of the hawk. |
|
Name |
String |
Name of the hawk. |
The SampleJmxHawk_hawkName also supports the following commands:
|
Method/Attribute |
Description |
|
flap |
Sets the wing mode to flap. |
|
setAngle |
Sets the angle of the hawk. |
|
setColor |
Sets the color of the hawk. |
|
soar |
Sets the wing mode to soar. |
An additional MBean is created for each gull, named SampleJmxGull_gullName with the following attributes:
|
Method/Attribute |
Type |
Description |
|
AllData |
TabularData |
One row, containing the angle, color and name of the gull. |
|
Angle |
int |
Angle of the gull. |
|
GullX |
double |
X location of the gull. |
|
GullY |
float |
Y location of the gull. |
|
Name |
String |
Name of the gull. |
|
Shape |
String |
Color of the gull. |
The SampleJmxGull_gullName also supports the following commands:
|
Method/Attribute |
Description |
|
flap |
Sets the wing mode to flap. |
|
fly |
Sets the wing mode to soar. |
|
setAngle |
Sets the angle of the gull. |
|
setColor |
Sets the color of the gull. |
Running the Sample JMX Application
From an initialized terminal window (see “Initializing a Command Prompt or Terminal Window”), type:
run_samplejmxapp
JMX Data Source Command Line Options
In addition to General Options, the following command line arguments are enabled with the JMX data source when you run RTView applications from a Windows Command Prompt or UNIX terminal window. See “Command Line Options: Display Builder and Display Viewer” for more information.
Note: If a command line argument contains a space or a semicolon, then the entire argument must be enclosed in quotes (e.g.: "-sub:$data:my Data").
-jmxautodiscover
Automatically discover local MBean Servers once each poll interval.
Note: Poll interval is determined by either the Default Poll Interval or according to the General Update Period specified in Application Options on the “General Tab”. See “Application Options - JMX” for more information.
Note: This option requires JDK 1.6 and you must include the tools.jar file (from your JDK installation) in “RTV_USERPATH”.
Example:
-jmxautodiscover
Filter auto-discovered connections (i.e. -jmxautodiscover:XXX, where XXX is the filter). The filter can be a single value or a ; (semicolon) delimited list of values.
Example:
-jmxautodiscover:com.sl;org.apache
This would limit auto-discovered connections to those that start with com.sl or org.apache.
-jmxconn
Define a JMX connection. Specify the connection name, host, port, user name and password.
Example:
-jmxconn:Myconnection host1 9998
-jmxdsCheckValidAttributeNames
Specifies to only use column names that the MBean recognizes. The given string array of column names is filtered by comparison against the most recent MBean list of valid column names. JMX MBeans are free to support or not support an attribute at any time.
Example:
-jmxdsCheckValidAttributeNames
Note: The jmxdsCheckValidAttributeNames option can also be specified in the initialization file JMXPTIONS.ini file. Options specified using command line arguments override values saved in initialization files.
-jmx_mbeans_change_dynamically:(true or false)
The jmx_mbeans_change_dynamically property works in conjunction with the jmx_optimize_mbics property (below) to optimize MBean Info Cache loading. The default setting is true.
MBean Info Caches are a set of local caches created by the RTView JMX data source. The JMX data source creates a cache for each MBean. Each cache contains data the MBean provides to users, as well as mapping information to corresponding Data Objects. The JMX data source uses these local caches to retrieve data updates.
Example:
-jmx_mbeans_change_dynamically:true
There are three possible configurations using these two properties:
1. jmx_optimize_mbics = false, jmx_mbeans_change_dynamically = true
If your JMX performance is sufficient, this configuration is appropriate. This is the default setting, and the method RTView has historically used. This method uses the Polling Data Mode to obtain data from the JMX Data Source and update MBean Info Caches. Updates occur as specified by the RTView Update Period.
There are two potential performance downsides in polling mode that the two properties can mitigate. With the polling mode: A) The JMX Data Source updates the MBean Info Caches even if it is not time to update the polled data. If the RTView Update Period is 10 seconds and the JMX Metrics Period is 30 seconds, there would be three updates for every polled data loading. The first two MBean Info Cache updates would happen and then the JMX data source would notice it was not time to update the polled data—thereby performing two unnecessary updates. The third update would coincide with the JMX Metrics Period and the MBean Info Caches would again be updated followed by a data update. And B) If there are no JMX Data Objects that need to be notified, the MBean Info Cache updates are unnecessary.
2. jmx_optimize_mbics = true, jmx_mbeans_change_dynamically = true
This configuration reduces update traffic by setting the MBean Info Cache updates to occur only just before the data is about to be updated. Use this setting if you see updates to the MBean Info Caches on the JMX Update period that do not get followed with a data update (Inefficiency A described above).
3. jmx_optimize_mbics = false or true, jmx_mbeans_change_dynamically = false
This provides the maximum in MBean Info Cache loading optimization as no periodic MBean Info Cache updates occur. Use this configuration if (a) your installation is not using Notified Data Objects or, (b) you are using Notified Data Objects but the beans are static. That is, the data on the beans may change but the beans themselves do not, thereby mitigating the need for MBean Info Cache updates (the code does initially fill the MBean Info Caches but their value remains static).
Note: When jmx_mbeans_change_dynamically is set to false, the setting for jmx_optimize_mbics is ignored. jmx_mbeans_change_dynamically overrides jmx_optimize_mbics.
Note: The jmx_mbeans_change_dynamically option can also be specified in the initialization file JMXPTIONS.ini. Options specified using command line arguments override values saved in initialization files.
-jmx_metrics_period
Enter the time in milliseconds to control how often MBean methods are executed. Default is 0, which executes MBean methods according to the update period specified on the Application Options General tab.
Note: Because the MBean Method Execution Interval is superseded by the General Update Period, the amount of time elapsed between method executions may be longer than the value entered. For example, if the General Update Period is 2000 milliseconds and the MBean Method Execution Interval is 5000 milliseconds, MBean methods will be executed every six seconds.
Example:
-jmx_metrics_period:5000
-jmx_minreconnecttime:(seconds)
Enter the minimum number of seconds that will elapse before attempting to reconnect. Default is 30.
Example:
-jmx_minreconnecttime:15
-jmx_optimize_mbics:(true or false)
The jmx_optimize_mbics property works in conjunction with the jmx_mbeans_change_dynamically property to optimize MBean Info Cache loading. The default setting is false. For details, see jmx_mbeans_change_dynamically.
Example:
-jmx_optimize_mbics:false
Note: The jmx_optimize_mbics option can also be specified in the initialization file JMXPTIONS.ini. Options specified using command line arguments override values saved in initialization files.
-jmx_use_multiple_threads:(true or false)
Enable multiple threads for commands and polled queries. Default is false. This option enhances performance in the case where some JMX servers are slow, thus preventing a single server (or servers) from delaying updates from all JMX servers.
Note: RTView will create one thread per connection, so this is not a practical option for cases where hundreds of connections are defined.
If true, then the thread that created the JMX connection will be used for all commands and polled queries on that connection. The polled queries will initiate based on the Poll Interval for the data attachment and each connection will update their listeners asynchronously when data becomes available.
If false, then polled queries are executed synchronously and the listener is not updated until the data from all connections in the data attachment has returned.
Example:
-jmx_use_multiple_threads:true
Note: The jmx_use_multiple_threads option can also be specified on the “JMX Administration Tab” of the Application Options dialog and saved to the JMXOPTIONS.ini file. Options specified using command line arguments override values saved in initialization files.