Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท Monitoring and Tuning

Monitoring Tomcat with JMX and the Manager

Learn how Tomcat exposes metrics through JMX MBeans, how to enable remote JMX safely, which attributes matter, and how the Manager status page and JVM beans help.

You cannot tune or troubleshoot what you cannot see. Tomcat is a Java program, so it has a built-in window into its own state: JMX (Java Management Extensions). Almost every Tomcat component registers itself as an MBean, a managed object with readable attributes (current thread count, active sessions, bytes sent) and sometimes operations (reload a context, stop a connector). Tools such as JConsole, VisualVM, Prometheus exporters and commercial monitors all read these beans.

This lesson shows the beans that matter, how to enable JMX access without opening a security hole, and how to read the same kind of data from Java code. The Tomcat parts are read-only; the runnable examples use the standard JVM beans every Java program has, which are the same API Tomcat's beans use.

What Tomcat publishes

Tomcat's beans live in the Catalina domain (and Tomcat for newer pieces). Useful object names:

Object name Attributes worth watching
Catalina:type=ThreadPool,name="http-nio-8080" currentThreadCount, currentThreadsBusy, maxThreads
Catalina:type=GlobalRequestProcessor,name="http-nio-8080" requestCount, errorCount, processingTime, bytesSent
Catalina:type=Manager,host=localhost,context=/app activeSessions, sessionCounter, expiredSessions, rejectedSessions
Catalina:type=DataSource,... numActive, numIdle for JNDI connection pools
Catalina:type=Cache,host=localhost,context=/app resource cache hitCount, lookupCount

Besides Tomcat's own, the JVM provides java.lang:type=Memory, GarbageCollector, Threading, OperatingSystem and ClassLoading. Together they answer: Is the thread pool saturated? Is memory climbing? How often does GC run? Are sessions piling up?

Enabling JMX

For local use, JConsole can attach to a running JVM on the same machine without any setup. For remote monitoring, add system properties in bin/setenv.sh (create the file if it does not exist; Tomcat's catalina.sh sources it):

Terminal
CATALINA_OPTS="$CATALINA_OPTS \
  -Dcom.sun.management.jmxremote.port=9010 \
  -Dcom.sun.management.jmxremote.rmi.port=9010 \
  -Dcom.sun.management.jmxremote.authenticate=true \
  -Dcom.sun.management.jmxremote.password.file=/opt/tomcat/conf/jmxremote.password \
  -Dcom.sun.management.jmxremote.access.file=/opt/tomcat/conf/jmxremote.access \
  -Dcom.sun.management.jmxremote.ssl=true \
  -Djava.rmi.server.hostname=10.0.0.11"

Never expose a JMX port without authentication and TLS: an open JMX port allows remote code execution, because a client can load arbitrary MBeans. Better still, bind the port to a private network or an SSH tunnel and firewall it. Tomcat also provides a JmxRemoteLifecycleListener for fixing the RMI port range, useful behind firewalls:

XML
<Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
          rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002"/>

The Manager application and the JMX proxy

Besides JMX clients, Tomcat's manager web app offers HTTP views. /manager/status shows memory, connector status, and per-request details; /manager/status?XML=true gives the same in XML for scripts. /manager/jmxproxy and the text interface (/manager/text/list, /text/serverinfo, /text/threaddump, /text/vminfo) let you query beans and fetch dumps with curl. These pages need a user with the manager-status, manager-jmx or manager-script role, so protect them with a strong password and an address restriction (see valves and access control).

Terminal
curl -u monitor:secret "http://localhost:8080/manager/jmxproxy?get=Catalina:type=ThreadPool,name=%22http-nio-8080%22&att=currentThreadsBusy"

For dashboards, most teams run a Prometheus JMX exporter as a Java agent (-javaagent:jmx_prometheus_javaagent.jar=9404:config.yaml) and graph the values in Grafana, alerting when currentThreadsBusy stays near maxThreads.

Reading beans from Java

The java.lang.management API gives typed access to the JVM's own beans, and the generic MBeanServer lets you read any bean by name. The first stand-in prints a few values; numbers differ between machines, so no output is shown here.

Java Stand-in: reading JVM MBeans

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Registering your own MBean

Applications can publish their own metrics next to Tomcat's. A standard MBean is an interface whose name ends in MBean plus a class implementing it. Register it with the platform server and JConsole shows it under its object name.

Java Stand-in: a custom MBean

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In a web application register beans in a ServletContextListener and unregister them in contextDestroyed. Forgetting to unregister causes InstanceAlreadyExistsException at the next reload, and a classloader leak (see memory leaks).

What to alert on

  • currentThreadsBusy close to maxThreads for minutes (see thread pools).
  • errorCount rising faster than requestCount.
  • Old-generation heap above 80% after collections, or frequent full GCs (see memory and GC tuning).
  • activeSessions growing without bound.
  • Data source numActive equal to its maximum.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an MBean?

    MBeans are the objects JMX clients read and call; Tomcat registers many of them.
  2. 2. Which attribute shows how many worker threads are currently handling requests?

    currentThreadsBusy of the ThreadPool bean counts threads in use right now.
  3. 3. Why must a remote JMX port use authentication and TLS?

    JMX clients can load classes and invoke operations, so an unprotected port is a remote-code-execution hole.
  4. 4. Where do you normally put CATALINA_OPTS for JMX flags?

    catalina.sh reads setenv.sh, so your settings survive Tomcat upgrades.

Summary

  • Tomcat and the JVM expose metrics as JMX MBeans; JConsole, VisualVM and exporters read them.
  • Watch thread pool use, error counts, sessions, heap and GC activity.
  • Secure remote JMX with authentication, TLS and network restrictions.
  • The Manager's status and jmxproxy pages are scriptable but must be protected.
  • Applications can register their own MBeans next to Tomcat's.

Next: Thread pools and connector tuning