Skip to main content

Tomcat integration

For general reference, follow the Application Agent page.

This page describes a workaround for a known issue with Tomcat support:

  1. Tomcat has a slight delay upon startup before it loads application files.
  2. The Application Agent scans classes immediately after the Java process starts and the agent is loaded.
  3. As a result, the Application Agent's scanning algorithm may finish before the application classes are fully loaded.

There are two ways to work around this issue, described below.

First, proceed with the common step of supplying the agent files to Tomcat.

Supply agent files to Tomcat#

  1. Deploy your application to Tomcat. Upon deployment, its files should be available in the tomcat/webapps directory.

  2. Place the Application Agent files in the tomcat/bin/agent directory.

  3. Set the CATALINA_OPTS environment variable for Tomcat to use the agent files:

    Windows

    set "CATALINA_OPTS=-agentpath:agent\drill_agent.dll"

    Linux

    export CATALINA_OPTS=-agentpath:agent/libdrill_agent.so

    Alternatively, you can set this directly in Tomcat's launch script (Windows: bin/catalina.bat, Linux: bin/catalina.sh).

Now you have two options to ensure the Application Agent successfully locates the application classes:

Option 1 - Specify path to application archive#

Specify the scanClassPath parameter to point to your application archive in Tomcat's directory.

You can set this in the drill.properties file, which comes with the Application Agent files:

# Adjust to match the actual path to your JAR or WAR file:
scanClassPath=../webapps/my-app.war
# You can specify multiple paths using the ";" delimiter
# scanClassPath=../webapps/my-app.war;../webapps/other-app.war
# This example uses relative paths, assuming Tomcat is launched
# with /tomcat/bin/catalina.bat (or .sh) script
# but absolute paths work too
# scanClassPath=C:/java/tomcat-10/webapps/helloworld.war

Or set the DRILL_SCAN_CLASS_PATH environment variable, following the same rules

  1. Restart Tomcat and wait. The Application Agent should detect your application classes and send data to Drill4J.

  2. Check Metabase to confirm it has information on the application classes.

Option 2 - Delay the class scanning#

If specifying the direct path to your application isn't possible or practical (for instance, you manage many apps and the list frequently changes), you can use the Application Agent's scanClassDelay parameter to delay the class scanning process.

Configure it in the drill.properties file, which is included with the Application Agent files.

scanClassDelay=5000

Or set DRILL_SCAN_CLASS_DELAY environment variable

Troubleshooting#

If your application classes aren't showing up in Metabase after Tomcat is restarted and your application is loaded:

  1. To confirm the agent is loaded, refer to the Application Agent Troubleshooting section.

  2. Double-check that the correct scanClassPath is specified.

  3. If you're using the scanClassDelay approach, ensure the value is large enough for Tomcat to load the application classes, so your app loads before the Application Agent starts scanning.

Limitations#

The Drill4J Application Agent cannot detect new applications deployed to Tomcat while it is already running. To allow the Application Agent to detect new application classes, Tomcat must be restarted.