Deploy the APM Java Agent
On successfully provisioning the APM Java agent, you can deploy the APM Java agent.
To deploy the APM Java agent on any Java application, you need to add the
-javaagent
parameter to the JVM startup script. Depending on the
Java environment, an application server or a microservice, users may have shell or bat
startup scripts, or another way to execute the Java command line.
See below examples on how to deploy the APM Java agent on the following Java applications:
Oracle WebLogic Server
Here's information on how to deploy the APM Java agent on the Oracle WebLogic Server.
- 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>
- Make a backup copy of the
startWebLogic.sh
file:cd $DOMAIN_HOME/bin cp startWebLogic.sh startWebLogic.sh.orig
- Use a text editor and edit the original
startWebLogic.sh
script and add the-javaagent
option.- 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 ofJAVA_OPTIONS
, after thesetDomainEnv.sh
call:JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:$DOMAIN_HOME/oracle-apm-agent/bootstrap/ApmAgent.jar"
- If you're deploying the APM Java agent on Managed Servers only, then add the following
-javaagent
option to the set ofJAVA_OPTIONS
within anif
statement after thesetDomainEnv.sh
call:if [ "$SERVER_NAME" != "AdminServer" ] ; then set JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:$DOMAIN_HOME/oracle-apm-agent/bootstrap/ApmAgent.jar" fi
- If you're deploying the APM Java agent on the Oracle WebLogic
Administration Server and Managed Servers, then add the following
- 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 ofstartWebLogic.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, thestopWebLogic.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.
- 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>"
- If you're using a Bash
shell:
- Make a backup copy of the
catalina.sh
file.$ cd $CATALINA_HOME/bin $ cp catalina.sh catalina.sh.orig
- Use a text editor and edit the original
catalina.sh
file and add the following-javaagent
option toCATALINA_OPTS
. Make the change outside of anyif
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"
- 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.
Jetty Server
Here's information on how to deploy the APM Java agent on the Jetty Server.
- 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
JETTY_HOME
variable to point to the Jetty Server destination directory (where the Jetty software was extracted) and confirm that the APM Java agent was provisioned in the same destination directory before you perform the next step. - Start the Jetty server.
java -javaagent:/<Destination_Directory>/oracle-apm-agent/bootstrap/ApmAgent.jar -jar $JETTY_HOME/start.jar
After the APM Java agent is successfully deployed, the Oracle APM
Agent: Initialized AgentInstance
message is displayed in the server startup
log.
Spring Boot
Here's information on how to deploy an APM Java agent on a Spring Boot microservice running embedded Apache Tomcat.
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.
-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 Oracle Container Engine for Kubernetes (OKE).
In some cases, deploying an APM Java agent in a container image is not possible. For example, if the user who is deploying an agent does not have the required access or permissions to rebuild a container image. In those cases, the solution is to deploy it on a mounted volume.
For details on how to deploy an APM Java agent on a mounted volume, watch the video: Kubernetes Spring Boot Instrumentation for Distributed Tracing or check out the blog: Application Performance Monitoring: Instrument Java on Kubernetes for Monitoring and Diagnostics.
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.
- 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. - 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>
- 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
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.
The below instructions are applicable for JBoss EAP and Wildfly.
- 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>"
- If you're using a Bash
shell:
- Make a backup copy of the
standalone.conf
file:cd $JBOSS_HOME/bin cp standalone.conf standalone.conf.orig
- Use a text editor and edit the original
standalone.conf
file and add the following Java options toJAVA_OPTS
. Make the change outside of anyif
statements or code blocks that may not be executed during server startup.- Add
-javaagent
option toJAVA_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"
.For example:
JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.oracle.apm"
Note
Each environment is different. The Jboss server's property may include different packages from what are shown in the above example.
- Add
- 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.