Tomcat How To


Many Java applications run in J2EE or JEE containers, such as Glassfish, JBoss or Tomcat. I will even go so far as to say that all serious Java applications today are written with the use of such application frameworks. From a monitoring perspective this is a great development. Not only does this standardise much of the infrastructure that applications use, these containers are usually heavily instrumented with JMX mbeans. This in turn means that there is lots to see through jconsole and Zabbix.

This page shows you how to enable the Zapcat bridge in Tomcat application servers. Most of the information here also applies to other servlet containers, such as JBoss, Jetty and OC4J.

Below is a schema of the setup that we will use in this tutorial. The Tomcat server runs on my development machine, instead of the sample agent application we used earlier.

Steps to Walk

In the root of the Zapcat distribution, you will find a Zapcat WAR file. Simply copy this file into Tomcat’s webapps directory. If all goes well, you will see that Tomcat expands the WAR file automatically.

You have to run Tomcat with “” on the command line. If you don’t, Tomcat will not create the management beans needed to monitor Tomcat itself. Tomcat probably does not automatically create these to avoid wasting memory on objects that are not used.

You can start a web browser and go to this new web application in Tomcat. If you do so, you should something like the screen shot below.

That’s all there is to it. You can now hook Zabbix up to the Zapcat agent, explore Tomcat’s JMX mbeans and make useful graphs of them in Zabbix.

Tomcat Template and Host Definition

Tomcat comes well-instrumented with mbeans. So many in fact, that you will have to make a careful selection what is worthwhile and what is not. To help you make sense of the whirlwind of statistics, Zapcat comes with a Tomcat template and a Tomcat host definition generator.

Using the template is straightforward, just locate the file named “Template_Tomcat.xml” in the directory “templates” of the Zapcat distribution. Upload this file to Zabbix and apply the template to your Tomcat instances.

Using the Tomcat template in real-life environments is rather tricky. The developers of Tomcat have chosen to use configuration items in the object names of the mbeans. That means that if you change for example the HTTP port number, the template stops working. Session graphs are only generated for the root web application and not for your own. Of course, you can take a text editor to the template and search-and-replace all occurrences of port numbers. That is tedious work, and it is easy to make mistakes.

To help you deal with this, the Zapcat web application provides a link where you can download the host definition file for your Tomcat installation. Right-click on the download link in the web application and save the file.

It is best to wait with generating the host definition file until you have set up Tomcat completely to your liking. Regenerate the host definition if you deploy new web applications, enable or disable connectors or change port numbers.

You can now upload this host definition into Zabbix using the regular import facility.

The newly imported definition will show up as a regular host, with a name derived from the server name that the Tomcat server runs on. You probably have to change the host name and IP addresses to suit your taste.

The host definition does not automatically include the items from the Java template or the Hibernate template. Don’t forget to link your new host definition with them, if applicable. This is done so that you may use custom versions of these templates for your Tomcats.

Looking at Tomcat

Before we can go into the items that are useful to monitor on a Tomcat instance, we have to sketch what Tomcat looks like from a monitoring perspective. This is especially important if you have to edit the Tomcat template manually.

In the image below, we see Tomcat as a system administrator might look at it. On the right, we see the web applications. Depending on your configuration there might be only one or two of them, or maybe ten or more.

On the left, we see the connectors. The connectors offer various ways to access the web applications. In this example, we see the HTTP and HTTPS connectors, plus a connector for linking Tomcat to an Apache web server through mod_jk. Connectors are configured in the application server’s configuration file. the file named “server.xml”.

There is really only one generic items of interest in Tomcat, and that is the version number of the application server. All the other items either belong to a connector or to a web applications.

Connector Monitoring

The connectors are the most interesting part of Tomcat to monitor. This is where the thread pooling happens, and where you can see the requests coming in and errors going out.

Of each connector, we monitor the number of requests per second, data sent and received per second and the processing time. These items are largely for information and analysis.

Thread pooling is interesting. Apart from the thread monitoring we already have in the Java template, we also find a per-connector thread pool in Tomcat. For each of these pools there is a graph and a trigger, making it easy to see how the pool is behaving.

The HTTP and HTTPS connectors have the capability to use gzip compression on their outgoing stream. It is entirely up to you to enable compression or not. The tradeoff is that it reduces your bandwidth usage at the expense of extra processor load. At the moment, bandwidth is more precious than processor cycles, so I usually enable gzip compression. There is a trigger warning you that compression is not being used.

Web Application Monitoring

Of the web applications, we monitor the number of sessions on that  application. Some programmers place fairly large quantities of data into the session store. In that case, getting a feel for the number of concurrent sessions may help trace the root cause of heavy memory use.

Finding Other MBeans in Tomcat

I have added a convenient page to the plugin that makes a list of all available mbeans in the running Tomcat instance. You can get to it by clicking on the link marked “mbean list”. This will take you to a page that looks like the one in the screenshot below.

You can use your browser’s text search function to find the beans you need. Notice how the formatting makes it easy for you to to cut and paste the queries into Zabbix as you add items.


As discusses in the how to, if the port number is already taken, you can specify a different port when you start Tomcat. Just set the system property “org.kjkoster.zapcat.zabbix.port” to the desired port number.

After you have changed the port number, you can recall the welcome page of your Zapcat WAR. It will show the currently configured port number and bind address. Obviously, this information is also available via JMX, so you can check the configuration in jconsole too.

Scope of the Managed Beans

As you know, JEE web applications are separated from one another using Java class loaders. This means that objects from one web application are invisible and unreachable for other web applications.

JMX mbeans do not follow these rules, though. They are global to the entire Tomcat instance. This means that when one web application registers an mbean, all applications in the web server can see and manipulate that bean. For the Zapcat web application this means that you do not have to put Zapcat inside the web application to access the JMX mbeans of that application.

I have not decided whether this is a good thing or not. In my mind, the global aspect of the mbean server breaks the container philosophy of JEE servlet containers. On the other hand, simply dropping the Zapcat WAR in and having instant access to all JMX mbeans in a Tomcat instance is nice and clean in its own right.

photo: Brian Lary
if you find this interesting, terrible or just would like to know more, e-mail
web statistics
download zapcat