Deploy the APM Java Agent

On successfully provisioning the APM Java agent, you can deploy the APM Java agent.

As a part of the APM Java agent deployment, a -javaagent option is used to hook the APM Java agent in the startup script of the application server or to a microservice.

The following sections provide specific information on how to deploy the APM Java agent on the following:

Oracle WebLogic Server

Here's information on how to deploy the APM Java agent on the Oracle WebLogic Server.

  1. Set a variable to point to your application server destination directory. This is the directory in which the APM Java agent is provisioned.

    Set the $DOMAIN_HOME variable to point to the Oracle WebLogic Server Domain directory and confirm that the APM Java agent was provisioned in the same destination directory before you perform the next step.

    Application Server Destination Directory Variable Information
    Oracle WebLogic Server Set the $DOMAIN_HOME variable to point to the Oracle WebLogic Server Domain.
    export DOMAIN_HOME=<Oracle WebLogic Server Domain>
  2. Make a backup copy of the startWebLogic.sh file:
    cd $DOMAIN_HOME/bin
    cp startWebLogic.sh startWebLogic.sh.orig
  3. Use a text editor and edit the original startWebLogic.sh script and add the -javaagent option.
    1. If you're deploying the APM Java agent on the Oracle WebLogic Administration Server and Managed Servers, then add the following -javaagent option to the set of JAVA_OPTIONS, after the setDomainEnv.sh call:
      JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:$DOMAIN_HOME/oracle-apm-agent/bootstrap/ApmAgent.jar"
    2. If you're deploying the APM Java agent on Managed Servers only, then add the following -javaagent option to the set of JAVA_OPTIONS within an if statement after the setDomainEnv.sh call:
      if [ "$SERVER_NAME" != "AdminServer" ] ; then
              set JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:$DOMAIN_HOME/oracle-apm-agent/bootstrap/ApmAgent.jar"
  4. Stop and restart the Oracle WebLogic Server:
    cd $DOMAIN_HOME/bin
    ./stopWebLogic.sh
    cd ..
    nohup ./startWebLogic.sh >& startup.log &

    If you have Managed Servers, stop and restart them too:

    cd $DOMAIN_HOME/bin
            ./stopManagedWebLogic.sh {SERVER_NAME} {ADMIN_URL} {USER_NAME} {PASSWORD}
            nohup ./startManagedWebLogic.sh {SERVER_NAME} {ADMIN_URL} >& {SERVER_NAME}.log &
    Note

    Notice that the $DOMAIN_HOME version of startWebLogic.sh is used, even though you edited the $DOMAIN_HOME/bin version. Invoking the command from one level higher (from $DOMAIN_HOME) invokes the command from a lower level (from $DOMAIN_HOME/bin). However, the stopWebLogic.sh command will be called from the $DOMAIN_HOME/bin directory.

After the APM Java agent is successfully deployed, the Oracle APM Agent: Initialized AgentInstance message is displayed in the server startup log.

Apache Tomcat Server

Here's information on how to deploy the APM Java agent on the Apache Tomcat Server.

  1. Set a variable to point to your application server destination directory. This is the directory in which the APM Java agent is provisioned.

    Set the $CATALINA_HOME variable to point to the Apache Tomcat Server destination directory and confirm that the APM Java agent was provisioned in the same destination directory before you perform the next step.

    Application Server Destination Directory Variable Information
    Apache Tomcat Server Set the $CATALINA_HOME variable to point to the Apache Tomcat Server destination directory.
    • If you're using a Bash shell:
      export CATALINA_HOME=<Apache Tomcat Server destination directory>
    • If you're using a C shell:
      setenv CATALINA_HOME "<Apache Tomcat Server destination directory>"
  2. Make a backup copy of the catalina.sh file.
    $ cd $CATALINA_HOME/bin
    $ cp catalina.sh catalina.sh.orig
  3. 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"
  4. Stop and restart the Apache Tomcat Server:
    $ cd $CATALINA_HOME/bin                      
    $ ./shutdown.sh
    $ ./startup.sh

After the APM Java agent is successfully deployed, the Oracle APM Agent: Initialized AgentInstance message is displayed in the server startup log.

For more information, see Install an APM Java Agent on a Tomcat Application Server Tutorial.

Spring Boot

Here's information on how to deploy an APM Java agent on a Spring Boot microservice running embedded Apache Tomcat.

It's assumed that you've completed the prerequisite tasks and provisioned the APM Java agent. Also, you must ensure that you've added the following properties to the Spring Boot application's application.properties file to enable Apache Tomcat Mbeans:
spring.jmx.enabled=true
server.tomcat.mbeanregistry.enabled=true

Alternatively, add the above properties: spring.jmx.enabled and server.tomcat.mbeanregistry.enabled as system properties on the command line.

To deploy the APM Java agent, add the following -javaagent option to the startup script of your microservice. Note that <Destination Directory> denotes the directory in which you provisioned the agent.
java -javaagent:<Destination Directory>/oracle-apm-agent/bootstrap/ApmAgent.jar -jar target/<microservice.jar>

After the APM Java agent is successfully deployed, the Oracle APM Agent: Initialized AgentInstance message is displayed in the microservice startup log.

Docker and Kubernetes

Here's information on how to deploy an APM Java agent in a Docker container and Kubernetes.

It's assumed that you've completed the prerequisite tasks and provisioned the APM Java agent. It's recommended that you provision the agent in any location on your local machine and then copy it to a Docker image.

  1. Modify your Dockerfile to copy the APM Java agent to a Docker image:
    COPY <DESTINATION_DIRECTORY>/oracle-apm-agent <Docker_Image_Directory>/oracle-apm-agent/

    Note that <DESTINATION_DIRECTORY> denotes the location on your local machine where you provisioned the APM Java agent and <Docker_Image_Directory> denotes the directory in the Docker image to which you're copying the APM Java agent. The <Docker_Image_Directory> could also be the application server destination directory in Docker, for example, $DOMAIN_HOME, if you're working with Oracle WebLogic Server.

  2. Add the following -javaagent option to the startup script of your application server:
    java -javaagent:<Docker_Image_Directory>/oracle-apm-agent/bootstrap/ApmAgent.jar -jar target/<appserver.jar>
  3. Build a new Docker image with the built-in APM Java agent and the modified startup script, and push the image to the registry.

If you use Kubernetes to manage your Docker containers, then update your Kubernetes configuration to use the new Docker image, and restart the Kubernetes pod.

Also, you can set additional dimensions to be reported from the Kubernetes pod using the Downward API, by copying the following environment and volume settings in the deployment specification (yaml file) of the Kubernetes pod. For information on the Downward API, see The Downward API in Kubernetes documentation.

Environment Settings

spec:
  containers:
  - name: <container-name>
    image: image: <your-registry>/<your-docker-image>:latest
    env:
      - name: APM_ATTRIBUTES_K8S_POD_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.name
      - name: APM_ATTRIBUTES_K8S_NAMESPACE_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.namespace
      - name: APM_ATTRIBUTES_K8S_NODE_NAME
        valueFrom:
          fieldRef:
            fieldPath: spec.nodeName

Volume Settings

spec:
  containers:
  - name: <container-name>
    image: image: <your-registry>/<your-docker-image>:latest
    volumeMounts:
      - name: apm-attributes-k8s
        mountPath: /etc/apm-attributes-k8s
    volumes:
      - name: apm-attributes-k8s
        downwardAPI:
         items:
           - path: "labels"
             fieldRef:
               fieldPath: metadata.labels
           - path: "annotations"
             fieldRef:
               fieldPath: metadata.annotations
Note

If the Kubernetes deployment does not have labels, annotations, or both, the Downward API for the same will cause an error when the application is deployed. In this case, you must remove the Downward API entry corresponding to metadata.labels, metadata.annotations, or both.

JBoss Server

Here's information on how to deploy the APM Java agent on the JBoss Server.

  1. Set a variable to point to your application server destination directory. This is the directory in which the APM Java agent is provisioned.

    Set the $JBOSS_HOME variable to point to the JBoss Server destination directory and confirm that the APM Java agent was provisioned in the same destination directory before you perform the next step.

    Application Server Destination Directory Variable Information
    JBoss Server

    Set the $JBOSS_HOME variable to point to the JBoss Server destination directory.

    • If you're using a Bash shell:
      export JBOSS_HOME=<JBoss Server destination directory>
    • If you're using a C shell:
      setenv JBOSS_HOME "<JBoss Server destination directory>"
  2. Make a backup copy of the standalone.conf file:
    cd $JBOSS_HOME/bin
    cp standalone.conf standalone.conf.orig
  3. Use a text editor and edit the original standalone.conf file and add the following Java options to JAVA_OPTS. Make the change outside of any if statements or code blocks that may not be executed during server startup.
    • Add -javaagent option to JAVA_OPTS.
      JAVA_OPTS="$JAVA_OPTS -javaagent:$JBOSS_HOME/oracle-apm-agent/bootstrap/ApmAgent.jar"
    • Edit Java property jboss.modules.system.pkgs to include "com.oracle.apm".
      JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.oracle.apm"
  4. Stop and restart the JBoss Server:
    cd $JBOSS_HOME/bin                      
    ./jboss-cli.sh -c :shutdown                        
    nohup ./standalone.sh -b 0.0.0.0&> startup.log &

After the APM Java agent is successfully deployed, the Oracle APM Agent: Initialized AgentInstance message is displayed in the server startup log.