This page describes how system administrators and developers can use MuleSoft Tcat Server to monitor JMX MBean attributes. These MBeans reside in the same Java virtual machine as the Tcat Server agent. If you would like to know more about the JMX standard, see the Oracle Java documentation page Monitoring and Management Using JMX.
By default, Tcat Server’s runtime environment enables the Java virtual machine’s JMX agent. If you are using a stock Apache Tomcat by deploying the Tcat agent, Tcat will enable JMX in your stock Tomcat’s JVM upon the first Tcat-controlled JVM restart.
Tomcat’s container system is designed such that every significant object is exposed over JMX as MBeans, with both attributes and operations. This applies to all Tomcat versions 4.0 and higher. Tomcat version 7.0.3 and higher has container MBeans that allow JMX remote instantiation, configuration, and lifecycle state changes, which makes it possible to remotely start and configure new Tomcat 7 instances via a JMX connection.
All versions of Tomcat implement a rich set of server MBeans that allow lightweight inspection of a rich set of attribute metrics. This includes Servers, Services, Connectors, thread pools (Executors), Engines, Hosts, webapps (WebModules), Valves, etc. All of these objects expose JMX attributes that are independently monitorable via JMX.
If you need to monitor Tomcat’s JMX MBeans from outside the Tomcat server machine (for instance monitoring Tomcat from a network monitoring console, such as jconsole or Nagios), you will need to enable a JMX remote server port in the Tomcat JVM. Beginning with Tomcat 6.0.26, a new JmxRemoteLifecycleListener was added that allows opening a JMX Remote server port over RMI where the server port is a fixed port number. Normally, the port number is random, and that does not usually work well in production because firewalls must be pre-configured to allow TCP connections to specified ports only.
|
Warning
|
NOTE: If you monitor your Tomcat’s MBeans via the Tcat Server console, you do not need to open a JMX Remote server port, and thus you do not need the JmxRemoteLifecycleListener.
|
The JmxRemoteLifecycleListener is part of the Tomcat "extras", and is a separate download – the listener is contained in the catalina-jmx-remote.jar file, which you can place in your Tomcat’s lib/ directory. You can configure it in server.xml by adding the following directly under the <Server> element, like this:
server.xml Snippet
<Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
rmiRegistryPort="10001" rmiServerPort="10002"/>with the following system properties set (eg in conf/Catalina/localhost/tcat-env.sh):
-Dcom.sun.management.jmxremote.password.file=${catalina.base}/conf/jmx-password.txt
-Dcom.sun.management.jmxremote.access.file=${catalina.base}/conf/jmx-access.txtThe jmx-password.txt file just needs to contain a single line containing the username and password, such as "admin mypassword". The jmx-access.txt file needs just a single line: "admin readwrite". On non-Windows operating systems, you can populate the files like this:
# echo 'admin mypassword' >$CATALINA_BASE/conf/jmx-password.txt# echo 'admin readwrite' >$CATALINA_BASE/conf/jmx-access.txt# chmod 600 $CATALINA_BASE/conf/jmx-password.txt $CATALINA_BASE/conf/jmx-access.txtAfter this is configured, restart the Tomcat JVM.
Then opening ports 10001 (RMI registry) and 10002 (JMX RMI server) in your internal LAN firewall would enable other machines in your LAN to connect to a Tomcat instance.
The Tcat Server console implements secure communication with all Tcat Server agent JVMs via HTTPS with X.509 client certificate authentication. Over this secure network connection, you may list JMX MBeans in the remote Tomcat JVM, you may inspect their attributes, and you may monitor their attribute values. The Tcat console allows you to configure charting arbitrary numeric JMX metrics, and also allows you to configure alerts for arbitrary numeric JMX metric values that go lower or higher than a threshold you choose.
The Tcat Server agent augments Tomcat’s JMX MBeans with additional MBeans that expose additional metrics as MBean attributes. Also, as part of the Tcat Server agent secure communications design, the Tcat agent allows JMX monitoring of your Tomcat JVMs without requiring opening any additional TCP network ports.
In the console, select one of the registered servers. This will take you to the Dashboard for that server. On the dashboard, you may add metric charts to the Server Metrics portlet.
Configure the Server Metrics portlet by clicking the configuration button on the Server Metrics portlet’s top right corner.
From the portlet configuration dialog, select that you want to add a new JMX Attribute chart type, and then you may click Browse to view the remote MBeanServer. These MBeans are registered with the remote JVM’s platform MBeanServer. This may include MBeans that are part of webapps, in addition to MBeans that are part of Tcat and Tomcat.
Navigate through the remote Tomcat JVM’s MBeans tree, and select an attribute whose value you want to chart. You may select any numeric attribute on any of the listed MBeans. Then, click Ok.
Then, finish filling out the JMX Attribute Chart Type Configuration dialog. Make sure to enter a Display Name for the attribute you’re monitoring, and type in a Period (in whole seconds). This is the period interval by which the attribute’s value will be sampled. Each time your attribute is sampled, the console invokes a method call to the agent JVM to read the value of the MBean attribute. The lower you set the sample period, the higher the network and CPU utilization, so we suggest that you use caution not to set the sample period too low. Next, decide if you want to chart deltas by checking or unchecking the Track Delta checkbox. If you would like to monitor this metric across all of your servers, you may check the Add to All Servers checkbox, and this metric chart will show up on the Server Metrics portlet on each of your server dashboards. Click Ok in the Chart Type Configuration dialog when you’re finished configuring the chart.
Then click Save in the Server Metrics configuration panel to apply the changes and begin monitoring and charting the metric you selected. You should see your new metric chart on the server dashboard.
Server Metrics portlet shows the new JMX attribute chart.
Tcat Server’s console can also monitor a JMX attribute metric and send an alert when the value equals or crosses a threshold you define. When defining a JMX Attribute alert type, you browse the remote server’s MBeans and select an attribute to monitor the same as we showed in the above section on charting a JMX MBean attribute. See the Working With Alerts and Defining Notifications and Destinations pages for detailed explanations and tutorials of the Tcat Server console’s built-in alerting features.