Tomcat Product Configuration

Overview

The Tomcat plugin manages Tomcat servers provided by Apache or JBoss EWS. Currently Tomcat 5 and Tomcat 6 are supported. The earliest Tomcat5 version tested with this plugin is 5.5.23. The earliest Tomcat6 version tested with this plugin is 6.0.18.

Enabling Numeric Metrics

Java 5 or higher is required when running Tomcat.

The RHQ Agent should automatically discover Tomcat Server processes and they can be imported into inventory. But the resources will have DOWN availability until they are properly JMX enabled.

Users of JBoss EWS have hooks already provided and should start by reading the RUNNING.txt in their Tomcat root directory. That includes instructions similar to those below but where possible the scripts and configuration files have already been seeded with comments and commented out settings and/or declarations.

Tomcat management is performed by utilizing the JMX interface provided by Tomcat. As such, remote JMX management needs to be enabled. To do this add the following section near the top of your bin/startup.sh (adapt for Windows as necessary):

# RHQ Management
#
# To enable Tomcat for RHQ management it is necessary to enable remote JMX access to the Tomcat server:
# 1) Choose an unused and accessible portNum
# 2) Update as necessary and uncomment the following lines:
#
# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.port=<port>"
# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.ssl=false"
#
# 3) Follow the steps for secure access as described in the following url. Update as necessary
#    and uncomment the following lines based on authenticated (recommended) or unauthenticated access.
#      http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html.
#
# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.access.file=<access-file-path>"
# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.password.file=<password-file-path>"
# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.authenticate=false"
# export JAVA_OPTS

Make the appropriate edits and (re)start the Tomcat server.

If you have configured JMX with authentication you will need to edit the Tomcat Server resource and add valid credentials. To do this navigate to the already imported Tomcat Server Resource. Continue to the Inventory->Connection subtab. Edit the definition, setting the user/password to valid values. On successful update, the Server availability should go green within a couple minutes.

Enabling Response Time Metrics

Before enabling Response Time metric collection in your Tomcat Server Monitoring Schedules you need to add a servlet filter to your application's web.xml and add the filter jar, provided by RHQ.

It is typically case that the filter is deployed across all applications, in which case you can add the following to the global web.xml in the <tomcat>/conf directory.

Configure Filter in web.xml

Add the following filter and filter mapping to web.xml. Uncomment when you want to activate the filter. Note, to only apply the filter to certain URL's, you can change the filter mapping's URL pattern and/or add additional filter mappings.

  <!-- ===== RHQ Response Time Metric Filter ===== -->
  <!-- This filter gathers response time information for processed requests -->
  <!-- for all hosted applications. This requires that the                  -->
  <!-- rhq-rtfilter-X.X.X.jar also be placed properly in the Tomcat         -->
  <!-- deployment. The jar file can be downloaded from the RHQ Server.      -->
  <!-- Using the GUI, navigate to the Administration page. Then click       -->
  <!-- 'Download Agent Connectors'.                                         -->
  <!-- Download connector-rtfilter.zip. Unzip to extract the jar.           -->
  <!--                                                                      -->
  <!-- Optional parameters                                                  -->
  <!--                                                                      -->
  <!--   chopQueryString  Filter directly chops off the query parameters    -->
  <!--                    from the URL? Default is true.                    -->
  <!--                                                                      -->
  <!--   logDirectory     Directory to which the logs are written.          -->
  <!--                                                                      -->
  <!--   logFilePrefix    Prefix to written logfile names.                  -->
  <!--                                                                      -->
  <!--   dontLogRegEx     Patterns that should not be logged.               -->
  <!--                                                                      -->
  <!--   matchOnUriOnly   Apply the dontLog pattern to the URI only?        -->
  <!--                                                                      -->
  <!--   timeBetweenFlushesInSec                                            -->
  <!--                    Seconds between auto flushes of the logfile.      -->
  <!--   maxLogFileSize   The maximum allowed size, in bytes, of the        -->
  <!--                    logfiles if a logfile exceeds this limit, the     -->
  <!--                    filter will truncate it; the default value is     -->
  <!--                    5242880 (5 MB)                                    -->
  <!--   vHostMappingFile Name of vhost mapping file. This properties file  -->
  <!--                    must be in the Tomcat process classpath.          -->
  <!--                                                                      -->
  <!-- NOTE: When enabling, also uncomment the RhqRtFilter filter below.    -->
  <!-- NOTE: When enabling, uncomment the start and end tags.               -->

<!-- start tag (also uncomment end tag)
   <filter>
       <filter-name>RhqRtFilter</filter-name>
       <filter-class>org.rhq.helpers.rtfilter.filter.RtFilter</filter-class>
-->

<!-- Optional parameters. Note these typically remain commented. Also,
     some of these values may be configurable on the relevant
     RHQ Server resource, via the RHQ GUI.
      
       <init-param>
           <param-name>chopQueryString</param-name>
           <param-value>true</param-value>
       </init-param>
       <init-param>
           <param-name>logDirectory</param-name>
          <param-value>/tmp</param-value>
       </init-param>
       <init-param>
           <param-name>logFilePrefix</param-name>
           <param-value>localhost_7080_</param-value>
       </init-param>
       <init-param>
           <param-name>dontLogRegEx</param-name>
           <param-value></param-value>
       </init-param>
       <init-param>
          <param-name>matchOnUriOnly</param-name>
          <param-value>true</param-value>
       </init-param>
       <init-param>
           <param-name>timeBetweenFlushesInSec</param-name>
           <param-value>73</param-value>
       </init-param>
       <init-param>
           <param-name>flushAfterLines</param-name>
           <param-value>13</param-value>
       </init-param>
       <init-param>
           <param-name>maxLogFileSize</param-name>
           <param-value>5242880</param-value>
       </init-param>       
-->

<!-- end tag (also uncomment start tag)
   </filter>
-->

  <!-- ===== RHQ Response Time Metric Filter Mapping ===== -->
  <!-- To limit to only certain applications various filters can be         -->
  <!-- defined. This will perform RT metric collection for all              -->
  <!-- applications.                                                        -->
  <!--                                                                      -->
  <!-- Note: Uncomment only when also enabling the RhqRtFilter above.       -->
<!--
   <filter-mapping>
       <filter-name>RhqRtFilter</filter-name>
       <url-pattern>/*</url-pattern>
   </filter-mapping>
-->

Deploy Filter Jar(s)

The connector-rtfilter.zip file contains two jar files:

The rtfilter JAR
The commons logging JAR

Placement of the jar files depend on the version of Tomcat.

Tomcat Version	Instructions
5.5	Only one jar file is required: Copy the rtfilter JAR file to <tomcat5>/common/lib>
6	Copy the rtfilter JAR file to <tomcat6>/lib> Copy the commons logging JAR to <tomcat6>/lib>