This topic describes how to create persistent JMX metrics from MBean attributes. For information on monitoring JMX metrics, see Monitor JMX.
There are many helpful JMX topics on the AppDynamics community to help you with platform-specific troubleshooting tips.
JMX Metric Rules and Metrics
You can add persistent JMX-based metrics to AppDynamics using metric rules. Once you create a persistent JMX metric, you can:
- View it in the Metric Browser
- Add it to a Custom Dashboard
- Create a health rule for it so that you can receive alerts
You can use the MBean Browser or JMX Metrics Rules Panel to create new metrics. MBean query expressions are supported.
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.
Access 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.
Configure JMX Metric Rules
To add an MBean and attributes, possibly based on complex matching 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.
Instance identifier is a field in JMX Object pattern that can be used to categorize the runtime context of MBean category that has the same set of attributes. For example, user has two HTTP ports: 8090 and 8181. But attributes are the same, say "currentThreadsBusy" and "maxThreads". If a JMX pattern has both HTTP and AJP, but the user is interested in monitoring only HTTP and not AJP thread pool, then user uses identifier, a name that matches "HTTP" so that only HTTP ports related MBean data is collected. Advanced MBean Matching Criteria is an optional control for matching against attribute values. Identify the attribute name and value to test, along with matching criteria, such as a substring match.
Without any instance identifier specified, a tree of resources or attributes is shown on the JMX Metric browser that matches the Object Name Match Pattern.
If you specify an instanceIdentifier like "instance identifier = path2 ", then it will end up showing the second level attributes on the top level also.
The above tree will be shown as follows. The PoolSize, which is in the second level, has also appeared to the top level.
For example, the following screenshot displays the MBean matching criteria for the "GCJMXMetric" 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 so by turning off transaction detection at the entry point. For information on disabling transaction detection, see Transaction Detection Rules.
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: