Skip to main content

Tomcat

This guide explains how to instrument a Java application running on Apache Tomcat by selecting a Linux agent or Windows agent for trace ingestion.

Prerequisites​

  • The Motadata Agent must be installed and running on the server where the Tomcat-based application is deployed. Also, the otelcol should be running as part of the Motadata Agent. To check the agent status, open a Linux terminal and run:
service motadata-agent status
  • Java version must be 8 or higher:
java -version
  • The Tomcat installation directory (i.e., CATALINA_HOME) is available, and you have permission to edit Tomcat startup configuration and restart Tomcat.
  • Confirm how Tomcat is started in your environment (script-based startup is assumed in this guide).

Configuration Steps​

Step1: Register the Application Service in Motadata AIOps

Go to Menu > Settings > APM > Application Registration. Clicking the Application Registration button, you can register a new application.

From the application registration screen, select the instrumentation type Host/VM or Docker.

Java Trace Configuration​

FieldDescription
Select AgentSelect the Host/VM where this application is running.
Select LanguageSelect Java from the language icons.
Service NameProvide a unique and meaningful name (for example, ERP).
Application PathSpecify the full path to the executable file used to start the application (for example, your Tomcat startup path if required by your internal standard).
Service Attributes(Tags)Add key–value tags to your application for better filtering and organizing data in Explorer. Attribute keys must be in lowercase (for example, apm.env = prod). To add multiple Key-Value pairs you can click the add icon.
Add Custom ParametersAllows you to define custom sampling or tagging parameters for advanced use cases. These optional parameters are passed to the agent (for example, version=4).

Clicking the Apply Configuration button, you need to run the displayed Setup Command to instrument your Java application. Add the displayed argument to your java -jar command and restart the service to collect Traces.

Step2: Configure Tomcat for Instrumentation

Tomcat instrumentation can be done using different methods. Follow the instructions based on how Tomcat is started in your environment.

This method keeps agent settings isolated and upgrade-safe by using setenv.sh.

Locate or Create setenv.sh​

Go to:

<CATALINA_HOME>/bin/

If setenv.sh does not exist, create it:

vi <CATALINA_HOME>/bin/setenv.sh

Replace <CATALINA_HOME> with your Tomcat installation path.

Stop Tomcat​

Use your standard stop method. If you use Tomcat scripts:

<CATALINA_HOME>/bin/shutdown.sh

Add Motadata Java Agent Configuration​

Add the following near the top of setenv.sh:

CATALINA_OPTS="${CATALINA_OPTS} \
-javaagent:/motadata/motadata/instrumentation/agents/java/motadata-javaagent.jar \
-Dotel.javaagent.configuration-file=/motadata/motadata/config/<ServiceName>.properties"

Replace <ServiceName> with the exact service name you registered in Motadata AIOps.

Make the file executable:

chmod +x <CATALINA_HOME>/bin/setenv.sh

Start Tomcat​

<CATALINA_HOME>/bin/startup.sh

Ensure Tomcat starts successfully and the Java agent is loaded without errors.

Step3: Verify APM Trace Ingestion

Once the application is running, verify the below points:

  • Confirm that the service has been registered successfully.
  • On the service registration screen, the Service Trace Collection Status should display Running.
  • Generate traffic on the application (open UI pages / call APIs) and confirm traces appear in APM Explorer.