1. Installing and Configuring Oracle Application Performance Monitoring
  2. Install and Configure APM Java Agent on Apache Tomcat

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 from CATALINA_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)

Gateway is not a mandatory component while deploying Oracle Application Performance Monitoring; you can use a gateway in the following scenarios:

  • 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)

For instructions on how to deploy a gateway, see Install a Gateway.

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

  1. From the main Oracle Management Cloud menu, navigate to Administration and Agents.

  2. 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.

  3. From the Agent Type dropdown list, select APM Agent.

  4. Click APM Java Agent.

  5. 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.

To install and provision the APM Java Agent:
  1. Navigate to the directory where you downloaded the APM Java Agent software.
  2. Run the provisioning script as per your installation preference:
    Installation Preference Provisioning Script
    Basic Installation 
    cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${CATALINA_HOME}
    Silent Installation 
    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${CATALINA_HOME} -no-prompt

    With Gateway

    If you are using more than one gateway, use the -additional-gateways option. 

    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${CATALINA_HOME} -gateway-host {gw_host_value} -gateway-port {gw_port_value} 
-additional-gateways https://<gw_host_1>:<gw_port_1>,https://<gw_host_2>:<gw_port_2>
    In a Proxy Environment 
    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${CATALINA_HOME} -ph {http_proxy_host} -pp {http_proxy_port} -pt {http_proxy_auth_token}

    • -d is the absolute path of the home directory of the WebLogic Server domain. The APM Java Agent will be installed under this directory.

    • -ph {http_proxy_host} (Optional) — the proxy server’s host name.

    • -pp {http_proxy_port} (Optional) — the proxy server’s port.

    • -pt {http_proxy_auth_token}(Optional) — the authorization token that the agent will use if the proxy server requires authentication. This parameter will be passed literally as the proxy authorization header to the proxy server.

    The command line displays your tenant name and the value you specified.
  3. When prompted, provide the value of the registration key that you've created or downloaded earlier.
    If you are running the provisioning script with the -no-prompt option, create a text file containing the value of registration key, and provide the path to the file.

    Example: ./ProvisionApmJavaAsAgent.sh -d mydir -no-prompt < regkey.txt where regkey.txt contains a single line with the registration key.

  4. Review the values and confirm. To change the values, enter n and run the script again with new values. 
  5. To proceed with the installation, enter y.
    The APM Java Agent is installed.
For syntax and more options that can be used with the ProvisionApmJavaAsAgent.sh script, see Syntax for Using the Installation Script.
Install APM Java Agent on a Microservice
When running the APM Java Agent provisioning script on an application or microservice using Spring Boot or similar embedded Tomcat framework, the installation is very similar to standalone Tomcat. First, if your microservice does not have a standard server home (DOMAIN_HOME, CATALINA_HOME etc.), you can simply choose an empty directory for it. Once it's provisioned, add: 
-javaagent:<path-to-agent>/apmagent/lib/system/ApmAgentInstrumentation.jar
to the startup command line or script for your application or microservice.
Example: 
java -javaagent:/u01/apmagent/lib/system/ApmAgentInstrumentation.jar -jar my-microservice-1.0-SNAPSHOT.jar
Provisioning APM Java Agent with Offline Installer

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

Modify the Startup Script of Your Apache Tomcat Server

To modify the catalina.sh script of your Tomcat server home:
  1. Make a copy of your catalina.sh file:
    % cd $CATALINA_HOME/bin
% cp catalina.sh catalina.sh.orig
  2. Using a text editor, edit the original catalina.sh file and add -javaagent to CATALINA_OPTS. Make the change outside of any if statements or code blocks that may not be executed during server startup. This will ensure the -javaagent flag is always added to the server startup options.
    CATALINA_OPTS="$CATALINA_OPTS -javaagent:${CATALINA_HOME}/apmagent/lib/system/ApmAgentInstrumentation.jar -Datlassian.org.osgi.framework.bootdelegation=oracle.apmaas.*,sun.*,org.apache.xerces,org.apache.xerces.*,org.apache.naming,org.apache.naming.*,org.apache.catalina,org.apache.catalina.*,org.apache.tomcat.util.*"

    The -Datlassian.org.osgi.framework.bootdelgation option is required if you are running an Atlassian Jira application.

  3. Restart the Tomcat Servers:
    % cd $CATALINA_HOME/bin                      
% ./shutdown.sh
% ./startup.sh

Verify APM Java Agent Installation

See Verify APM Java Agent Installation.

Apache Tomcat On Windows: Requirements and Installation Instructions

Download the APM Java Agent Software for Apache Tomcat

  1. From the main Oracle Management Cloud menu, navigate to Administration and Agents.

  2. 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.

  3. From the Agent Type dropdown list, select APM Agent.

  4. Click APM Java Agent.

  5. 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.

To install and provision the APM Java Agent:
  1. Navigate to the directory where you downloaded the APM Java Agent software.
  2. Run the provisioning script as per your installation preference:
    Installation Preference Provisioning Script
    Basic Installation 
    
ProvisionApmJavaAsAgent.cmd /d %CATALINA_HOME% -no-wallet
    Silent Installation Download the registration key from the console and provide the value:
    
ProvisionApmJavaAsAgent.cmd /d %CATALINA_HOME%-no-prompt -regkey-file key.txt

    With Gateway

    If you are using more than one gateway, use the -additional-gateways option. 

    
ProvisionApmJavaAsAgent.cmd /d %CATALINA_HOME% -no-wallet -gateway-host {gw_host_value}, -gateway-port {gw_port_value} 
-additional-gateways https://<gw_host_1>:<gw_port_1>,https://<gw_host_2>:<gw_port_2>
    In a Proxy Environment 
    
ProvisionApmJavaAsAgent.cmd /d %CATALINA_HOME% -no-wallet -ph {http_proxy_host} -pp {http_proxy_port} -pt {http_proxy_auth_token}

    • -d is the absolute path of the home directory of Apache Tomcat. The APM Java Agent will be installed under this directory.

    • -ph {http_proxy_host} (Optional) — the proxy server’s host name.

    • -pp {http_proxy_port} (Optional) — the proxy server’s port.

    • -pt {http_proxy_auth_token}(Optional) — the authorization token that the agent will use if the proxy server requires authentication. This parameter will be passed literally as the proxy authorization header to the proxy server.

    The command line displays your tenant name and the value you specified.
  3. When prompted, provide the value of the registration key that you've created or downloaded earlier.
    If you are running the provisioning script with the -no-prompt option, create a text file containing the value of registration key, and provide the path to the file.

    Example: ProvisionApmJavaAsAgent.cmd /d mydir -no-prompt < regkey.txt where regkey.txt contains a single line with the registration key.

  4. Review the values and confirm. To change the values, enter n and run the script again with new values. 
  5. To proceed with the installation, enter y.
    The APM Java Agent is installed.

Modify the Startup Script of Your Apache Tomcat Server

To modify the catalina.bat script of your Tomcat server home:
  1. Make a copy of your catalina.bat file:
    cd %CATALINA_HOME%\bin
% cp catalina.bat catalina.bat.orig
  2. Using a text editor, edit the original catalina.bat file and add the -javaagent to CATALINA_OPTS. Make the change outside of any if statements or code blocks that may not be executed during server startup. This will ensure the -javaagent flag is always added to the server startup options.
    set CATALINA_OPTS=%CATALINA_OPTS%
      -javaagent:"%CATALINA_HOME%\apmagent\lib\system\ApmAgentInstrumentation.jar"

    The -Datlassian.org.osgi.framework.bootdelgation option is required if you are running an Atlassian Jira application.

  3. Restart the Tomcat Servers:
    cd %CATALINA_HOME%\bin                      
shutdown.bat
startup.bat

Verify APM Java Agent Installation

See Verify APM Java Agent Installation.

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

    1. Stop the Apache server:

      C:\tomcat\apache-tomcat-9.0.2-windows-x64\apache-tomcat-9.0.2/bin>shutdown

    2. 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

    3. 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

    1. 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

    2. 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, select TomEE.exe instead. If you have trouble using TomEE.exe, see this troubleshooting tip, Unable to open TomEE service during installation.
    3. 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

      This is an image of the tomcat8w.exe Java options properties. Add APMAgentInstrumentation.jar to the list of Java Options.
    4. Start your Apache server: 
      C:\tomcat\apache-tomcat-8.5.27-windows-x64\apache-tomcat-8.5.27/bin>startup