4 Install and Configure APM Java Agent on Apache Tomcat
Here are the requirements and instructions to install APM Java Agent on Apache Tomcat.
Apache Tomcat on Linux: Requirements and Installation Instructions
Prerequisites for Deploying APM Java Agent on an Apache Tomcat Server
-
Supported versions of Apache Tomcat Server: 6, 7, 8, 8.5, 9 and TomEE.
-
JDK version 1.7 or above. If you are using JDK 1.6, either use a JDK 1.6 that supports TLS 1.2 security protocol, or connect to OMC through a Gateway.
-
If the JDK version you are running doesn't support TLS 1.2 security protocol, refer to My Oracle Support Doc ID 2703411.1 before proceeding with the APM agent installation.
-
Other considerations:
-
The machine hosting the Apache Tomcat Server should be able to establish an HTTPS connection either directly or indirectly (using a proxy server or an Oracle Management Cloud gateway) to Oracle Management Cloud. For more information about Oracle Management Cloud gateway, see Install a Gateway.
-
The HTTPS connection must use TLS 1.2 security protocol.
-
The install user of APM Java Agent should be the same as the Apache Tomcat user.
-
The Apache Tomcat Server user should have read and write permissions to the directories that host the APM Java Agent, as well as the
CATALINA_BASE
APM Java Agent logging and config directories if different fromCATALINA_HOME
. -
If you are installing the APM Java Agent on minor Tomcat version 6.0.20 or earlier, please add the following command line option to enable local monitoring:
-Dcom.sun.management.jmxremote
-
Set the DESTINATION
Variable
Set the CATALINA_HOME
variable to point to the Tomcat destination directory.
-
If you're using a Bash shell:
export CATALINA_HOME=<Tomcat destination directory>
-
If you're using a C shell:
setenv CATALINA_HOME "<Tomcat destination directory>"
Deploy a Gateway (Optional)
-
If you have an application server that does not support Transport Layer Security (TLS) protocol 1.2
-
If you have older versions of Java Application Servers with JDK less than 1.7 (for example, Oracle WebLogic 10.3.6)
Set the Gateway Variables (Optional)
Set the values for Gateway host and port.
-
If you're using a Bash shell:
export GW_HOST=<Gateway Host Name> export GW_PORT=<Gateway Port>
-
If you're using a C shell:
setenv GW_HOST "<Gateway Host Name>" setenv GW_PORT "<Gateway Port>"
If you are using more than one gateway, use the -additional-gateways
option with the provisioning script.
Download the APM Java Agent Software for Apache Tomcat
-
From the main Oracle Management Cloud menu, navigate to Administration and Agents.
-
On the Oracle Management Cloud Agents page, click the Action Menu on the top right corner of the page and select Download Agents.
The Agent Software Download page is displayed.
-
From the Agent Type dropdown list, select APM Agent.
-
Click APM Java Agent.
-
Extract the contents of the installer ZIP file.
Install and Provision APM Java Agent on Apache Tomcat
-
Before you install the APM Java Agent, log in to the machine running the application server as a user who installed the application server.
-
The application server user should have Read-Write access to the APM Java Agent directories.
ProvisionApmJavaAsAgent.sh
script, see Syntax for Using the Installation Script.
-javaagent:<path-to-agent>/apmagent/lib/system/ApmAgentInstrumentation.jar
to the startup command line or script for your application or microservice.java -javaagent:/u01/apmagent/lib/system/ApmAgentInstrumentation.jar -jar my-microservice-1.0-SNAPSHOT.jar
You can install and provision the APM Java Agent from an offline installer that you have received over email.
To install from the emailed ZIP, the provisioning script needs to download the configuration file from Oracle Management Cloud. Specify these additional options while running the provisioning script:
Option | Description |
---|---|
-tenant-id |
The Oracle Management Cloud tenant name. |
-omc-server-url |
The URL of the Oracle Management Cloud server. Example: https://omchost:port |
Apache Tomcat On Windows: Requirements and Installation Instructions
Download the APM Java Agent Software for Apache Tomcat
-
From the main Oracle Management Cloud menu, navigate to Administration and Agents.
-
On the Oracle Management Cloud Agents page, click the Action Menu on the top right corner of the page and select Download Agents.
The Agent Software Download page is displayed.
-
From the Agent Type dropdown list, select APM Agent.
-
Click APM Java Agent.
-
Extract the contents of the installer ZIP file.
Install and Provision APM Java Agent on Apache Tomcat on Windows
-
Before you install the APM Java Agent, log in to the machine running the application server as a user who installed the application server.
-
The application server user should have Read-Write access to the APM Java Agent directories.
Configure the APM Agent as a Windows Service
Before you can manage your application, you must configure the APM Agent in Apache Tomcat as a Windows service.
Set the JvmArgs variable depending on your Apache Tomcat version:
-
Apache Tomcat 9
-
Stop the Apache server:
C:\tomcat\apache-tomcat-9.0.2-windows-x64\apache-tomcat-9.0.2/bin>shutdown
-
Run the following command:
set JvmArgs=javaagent:<path-to-APM>/apmagent/lib/system/ApmAgentInstrumentation.jar
-
Example:
set CATALINA_HOME=" C:\tomcat\apache-tomcat-9.0.2-windows-x64\apache-tomcat-9.0.2"
set JvmArgs=javaagent:%CATALINA_HOME%/apmagent/lib/system/ApmAgentInstrumentation.jar
-
-
Start your Apache server:
C:\tomcat\apache-tomcat-9.0.2-windows-x64\apache-tomcat-9.0.2/bin>startup
-
-
Apache Tomcat 8.5, 8, 7, 6
-
Change directory to the Apache bin folder:
cd C:\tomcat\apache-tomcat-8.5.27-windows-x64\apache-tomcat-8.5.27\bin
Stop the Apache server:
C:\tomcat\apache-tomcat-8.5.27-windows-x64\apache-tomcat-8.5.27/bin>shutdown
-
Double click tomcat<version_number>w.exe or run it from the command line.
For example, if you have Tomcat version 8, double click or run tomcat8w.exe.
Note:
If you are installing APM Agent on a TomEE server, selectTomEE.exe
instead. If you have trouble using TomEE.exe, see this troubleshooting tip, Unable to open TomEE service during installation. -
When the Properties window pops up, click the Java tab and add the following line to the Java Options:
-javaagent:C:\tomcat\apache-tomcat-8.5.27-windows-x64\apache-tomcat-8.5.27\apmagent\lib\system\ApmAgentInstrumentation.jar
-
Start your Apache server:
C:\tomcat\apache-tomcat-8.5.27-windows-x64\apache-tomcat-8.5.27/bin>startup
-