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.

Linux

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.

Host/VM

Java Trace Configuration

Field	Description
Select Agent	Select the Host/VM where this application is running.
Select Language	Select Java from the language icons.
Service Name	Provide a unique and meaningful name (for example, ERP).
Application Path	Specify the full path to the executable file used to start the application (for example, your Tomcat startup path if required by your internal standard).

Providing these details displays Setup Command to instrument your Java application. Copy the command snippet and use it while configuring Tomcat.

Docker

Java Trace Configuration

Field	Description
Select Agent	Select the Linux agent that can access the Docker host where Tomcat is running.
Language	Select Java from the language icons.
Service Name	Provide a unique and meaningful name (for example, ERP).
Application Path	Specify the container-side path as per your runtime standard.

Providing these details displays Setup Command to instrument your Java application. Copy the snippet and pass it to Tomcat via container startup configuration (for example, using CATALINA_OPTS).

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.

setenv.sh Method

Tomcat Started Using Standard Scripts (Recommended)

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

catalina.sh Method

Tomcat Started Using catalina.sh (Fallback)

Use this only if setenv.sh is not viable in your environment.

Locate catalina.sh

<CATALINA_HOME>/bin/catalina.sh

Stop Tomcat

<CATALINA_HOME>/bin/shutdown.sh

Modify catalina.sh

Open the file:

vi <CATALINA_HOME>/bin/catalina.sh

Add/export the CATALINA_OPTS before the exec line (the line that launches Java):

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

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

Start Tomcat

<CATALINA_HOME>/bin/startup.sh

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

Step3: Configure Attributes and Parameters

After configuring the application, you can provide the below details:

Field	Description
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 Parameters	Allows 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, the ingestion gets started.

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.

Windows

Prerequisites

• The Motadata Agent must be installed and running on the server where the Tomcat-based application is deployed. To verify agent status: press Win+R and open:

service.msc

• Java version must be 8 or higher (run from Command Prompt):

java -version

• The Tomcat installation directory (i.e., CATALINA_HOME) is available.
• You have permission to edit Tomcat startup configuration (.bat) and restart Tomcat.

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 as Host/VM.

Java Trace Configuration

Field	Description
Select Agent	Select the Host/VM where this application is running.
Select Language	Select Java from the language icons.
Service Name	Provide a unique and meaningful name (for example, ERP).
Application Path	Specify the full path as per your environment standard (if required by your setup).

Providing these details displays Setup Command to instrument your Java application. Copy the snippet and use it while configuring Tomcat.

Step2: Configure Tomcat for Instrumentation

Tomcat instrumentation on Windows can be done using multiple methods. Follow the instructions based on how Tomcat is started in your environment. Choose one method only.

setenv.bat Method

Tomcat Started Using Standard Scripts (Recommended)

Locate or Create setenv.bat

Go to:

%CATALINA_HOME%\bin\

Create or edit:

%CATALINA_HOME%\bin\setenv.bat

Stop Tomcat

Stop Tomcat using your standard approach (Windows Service / scripts / your enterprise wrapper).

Add Motadata Java Agent Configuration

Add the following line in setenv.bat:

set "CATALINA_OPTS=%CATALINA_OPTS% ^
-javaagent:C:\motadata\motadata\instrumentation\agents\java\motadata-javaagent.jar ^
-Dotel.javaagent.configuration-file=C:\motadata\motadata\config\<ServiceName>.properties"

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

Start Tomcat

Start Tomcat using your standard method.

Windows Service Restart

Tomcat Running as a Windows Service

If Tomcat is installed as a Windows Service, you still configure the agent using setenv.bat, then restart the service from Services (service.msc).

1. Open Services (service.msc)
2. Locate the Tomcat service
3. Restart the service

Ensure Tomcat starts successfully and the Java agent loads without errors.

Step3: Configure Attributes and Parameters

After configuring the application, you can provide the below details:

Field	Description
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 Parameters	Allows 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, the ingestion gets started.

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.