This topic describes how to create persistent JMX metrics from MBean attributes. For information on monitoring JMX metrics, see Monitor JMX MBeans.
JMX Metric Rules and Metrics
A JMX Metric Rule maps a set of MBean attributes from one or more MBeans into AppDynamics persistent metrics. You configure a metric rule that creates one or more metrics in AppDynamics. You may want to create new metrics if the preconfigured metrics do not provide sufficient visibility into the health of your system.
After the MBean attribute is configured to provide a persistent metric in AppDynamics, you can use it to configure health rules. For details see Health Rules. To view the MBeans that are reporting currently in your managed environment use the Metric Browser.
You can use the MBean Browser or the JMX Metrics Rules Panel to create new metrics, as described in the following sections. MBean query expressions are supported.
Required User Permissions
To configure new JMX Metrics your user account must have "Configure JMX" permissions for the application. For information about configuring user permissions for applications in Roles and Permissions.
Accessing the MBean Browser
If the MBean is already monitored and you want to create a metric from one of its attributes, you can do so from the MBean Browser.
To create a metric from an existing MBean attribute:
- Open the Node Dashboard of the node that hosts the MBean, and click the JMX tab and MBean Browser subtab.
- Expand the domains listed in the left panel and select the MBean that contains the attribute of interest.
- In the right panel, expand the Attributes section, select the attribute, and click Create Metric.
Accessing the JMX Metric Rules Configuration
To add an MBean and attributes, with the option of matching complex patterns, go to Configuration > Instrumentation and click the JMX tab.
In the JMX Metric Configurations panel, click the Java platform to add the metric to a platform group. Alternatively, create a new group at the top of the platform list and add your metric to the group.
Groups give you a way to organize metrics as it makes sense for you. For example, you may choose to keep custom metrics with their Java platform, or put all metrics you add into a "Custom" group to differentiate them from out-of-the-box metrics.
JMX Metric Settings
The general settings for adding instrumentation for an MBean are:
- The Name is the identifier you want to display in the UI for the MBean.
- An Exclude Rule excludes matched MBeans that would otherwise be included by other rules. See Exclude MBean Attributes.
- Enabled means that you want this rule to be applied.
- The Metric Path determines where the metric appears in the metric browser. For example, in the screenshot below, the metric path is "Web Container Runtime" for JMX metric "Tomcat_HttpThreadPools".
In the MBeans subpanel, add matching criteria to identify the MBeans that you want to monitor.
- The Domain name is the Java domain. This property must be the exact name; no wildcard characters are supported.
- The Object Name Match Pattern is the full object name pattern. The property may contain wildcard characters, such as the asterisk for matching all the name/value pairs. For example, specifying "jmx:type=Hello,*" matches a JMX MBean ObjectName, "jmx:type=Hello,name=hello1,key1=value1".
- The Instance Identifier is the MBean ID.
- The Advanced MBean Matching Criteria is an optional control for matching against attribute values. Identify the attribute name and value to test, along with a matching criteria, such as a substring match.
For example, the following screenshot displays the MBean matching criteria for the "Tomcat_HTTPThreadPools" rule.
For all matched MBeans, you can define one or more metrics for the attributes of those MBeans:
- Metric Getter Chain Expressions can be executed against any value. In addition, getter chains for Strings and Booleans are supported using implicit conversion. See MBean Getter Chains.
- Metric Time Rollup determines how the metric will be aggregated over a period of time. You can choose to either average or sum the data points, or use the latest data point in the time interval.
- Metric Cluster Rollup defines how the metric will be aggregated for a tier, using the performance data for all the nodes in that tier. You can either average or sum the data.
- Metric Aggregator Rollup defines how the Agent rolls up multiple individual measurements (observations) into the observation that it reports once a one minute. For performance reasons, Agents report data to the Controller at one minute intervals. Some metrics, such as Average Response Time, are measured (observed) many times in a minute. The Metric Aggregator Rollup setting determines how the Agent aggregates these metrics. You can average or sum observations on the data points or use the current observation. Alternatively you can use the delta between the current and previous observation.
In the following configuration, for example, the maxThreads MBean attribute is mapped to the Maximum Threads metric in the JMX metrics browser:
Export and Import JMX Configuration
After modifying the JMX configuration, you can backup or transfer the configuration using the JMX Configurations export and import icons at the top of the JMX Metric Configuration panel on the JMX instrumentation page. The configuration is exported as an XML file.
Disable Transaction Monitoring for JMX Monitored Nodes
In some circumstances, such as for monitoring caches and message buses, you want to collect JMX metrics without the overhead of transaction monitoring.
You can do this by turning off transaction detection at the entry point. For information on disabling transaction detection, see Business Transaction Detection.
MBean Getter Chains
Getter chains in custom MBean configuration specify the method that retrieves the value of interest.
Expressions can be executed against any value. In addition to getter chain support for numeric boxed primitives (Short, Integer, Long, and so on), Strings and Booleans are supported using implicit conversion.
Boolean and String are implicitly converted to an Integer, as follows:
- Booleans are automatically converted to 0 (false) and 1 (true).
- Strings are converted to numeric values.
To illustrate how to use a getter chain, given the following class with a getSomething() method that returns the time:
The metric getter chain configuration would be:
Watch the Video
For full-screen viewing, click Utilizing JMX Metrics.