Before you Begin

This tutorial shows you how to install an APM Java Agent on a Tomcat Application Server.

Background

APM Java Agents can record application server spans and metrics and send them to Application Performance Monitoring Cloud Service for analysis.

Perform Prerequisites

  1. Check the supported application servers and versions. In this example, the application server is Apache Tomcat/7.0.68 JDK8, on a Linux system.
  2. Make a note of your application server installation home.

    3. Note:

    You need total disk space of approx 175MB for the Agent.
  3. Perform Oracle Cloud Infrastructure Prerequisites, if you don't aready have an OCI environment set up:

Step 1: Create an APM domain

  1. Sign in to the Oracle Cloud Infrastructure console, open the navigation menu, and click Observability and Management. Under Application Performance Monitoring, click Administration and then Create Domain:

    Description of 1.png follows
    Description of the illustration 1

  2. View your newly created domain and make a note of the Data Upload Endpoint:

    Description of 2.png follows
    Description of the illustration 2

  3. When you create an APM Domain, a pair of private/public keys is generated automatically. Make a copy of the private key that was generated for your domain by clicking Copy.

    Description of 3.png follows
    Description of the illustration 3

Step 2: Download the Agent Files

  1. Navigate to Download APM Agent and click Java Agent and save the agent jar file:

    Description of 4.png follows
    Description of the illustration 4

  2. Check the checksum of the downloaded file to confirm your copy is identical to the one available on the APM Download page:

    sha256sum apm-java-agent-installer-1.1.jar

  3. Copy the agent jar file to your app sever host, if needed.

Step 3: Provision the APM Java Agent

The Java Agent destination can be any directory you choose. As best practice, in this example it is provisioned in the CATALINA_HOME, the location of the Apache Tomcat. First, navigate to the directory when your agent .jar file is. Then enter the following commands to provision the agent:

    setenv JAVA_HOME /opt/jdk8
    setenv CATALINA_HOME /u01/tomcat/orderApp-tomcat4
    java -jar ./apm-java-agent-installer-1.1.jar provision-agent -service-name=my_service -destination=$CATALINA_HOME -private-data-key=AAA5UN2C6YOWWWUZ5Q7UUU3QACF4BBB -data-upload-endpoint=https://aaaaaaaaaaaaaaaaaaaa-ashburn-1.oci.oraclecloud.com

    Sample output:

    Action [provision-agent] completed successfully
    ********************************************
    APM Agent has been provisioned successfully. To complete the setup, you need to
    modify your destination's appserver startup script so that the APM Agent you
    have just deployed can be started. Here is the general information on the changes [...]

Step 4: Deploy the APM Java Agent

  1. Make a backup copy of the catalina.sh file.

    cd CATALINA_HOME/bin
    cp catalina.sh catalina.sh.orig

  2. Use a text editor and edit the original catalina.sh file and add the following -javaagent option 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 that the -javaagent flag is always added to the server startup options.

    CATALINA_OPTS="${CATALINA_OPTS} -javaagent:$CATALINA_HOME/oracle-apm-agent/bootstrap/ApmAgent.jar"

  3. Stop and restart the Apache Tomcat Server:

    cd $CATALINA_HOME/bin
    ./shutdown.sh

    Sample output:

    Using CATALINA_BASE: /u01/tomcat/orderApp-tomcat4
    Using CATALINA_HOME: /u01/tomcat/orderApp-tomcat4
    Using CATALINA_TMPDIR: /u01/tomcat/orderApp-tomcat4/temp
    Using JRE_HOME: /opt/jdk8
    Using CLASSPATH: /u01/tomcat/orderApp-tomcat4/bin/bootstrap.jar:/u01/tomcat/orderApp-tomcat4/bin/tomcat-juli.jar
    Catalina home is /u01/tomcat/orderApp-tomcat4
     
    ./startup.sh

    Sample output:

    Using CATALINA_BASE: /u01/tomcat/orderApp-tomcat4
    Using CATALINA_HOME: /u01/tomcat/orderApp-tomcat4
    Using CATALINA_TMPDIR: /u01/tomcat/orderApp-tomcat4/temp
    Using JRE_HOME: /opt/jdk8
    Using CLASSPATH: /u01/tomcat/orderApp-tomcat4/temp/bin/bootstrap.jar:/u01/tomcat/orderApp-tomcat4/bin/tomcat-juli.jar
    Catalina home is /u01/tomcat/orderApp-tomcat4

Step 5: Verify Your APM Java Agent Deployment

Verify that your agent was successfully deployed by looking at the agent deployment logs as well as the Application Performance Monitoring Cloud Service user interface. The Agent is provisioned in $CATALINA_HOME/oracle-apm-agent.

  1. The logs are located in the agent location you chose above.

    cd $CATALINA_HOME/oracle-apm-agent
    The log directory should have the following log files: AgentErrors.log, Agent.log, AgentStartup.log, AgentStatus.log
  2. Check the AgentStartup.log file and look for a success message: 
    cat AgentStartup.log
    Agent successfully initialized
  3. Check the AgentStatus.log file and look for short status messages that indicate that the APM Java agent is active.
  4. Navigate to Application Performance Monitoring , click on Trace Explorer and check that trace data from the application server is being uploaded.

Note:

The Agent typically requires about 200MB of JVM memory heap space, so you may need to adjust the JVM's memory heap settings (-Xmx) appropriately.

Learn More