Install

Please follow the instruction for your platform to install the java agent on the host system. Then follow the instructions to enable the agent for your application server.

Getting the agent jar

Linux

  1. Create and navigate to the desired agent installation location
  2. Download agent installation script $ curl -sSO https://files.appoptics.com/appoptics-java.sh
  3. Execute the installation script $ bash appoptics-java.sh --service-key=<your service key> This downloads the agent jar file appoptics-agent.jar, the sdk jar file appoptics-sdk.jar, and the agent configuration file javaagent.json.

Windows

  1. Download agent installer from https://files.appoptics.com/java/latest/JavaAgent_Setup.exe
  2. Run the installer and provide your service key when requested

Heroku

Ensure that the AppOptics add-on is attached to your Heroku application, then follow the Java agent steps to install and enable the agent.

Azure Windows App Service

  1. Remote into the App Service (for example with Kudo Shell/CMD).
  2. Navigate to D:\home\site\wwwroot. Create a folder for the AppOptics Java APM agent, for example “AppOptics”
  3. Download the agent jar and config json files to the created folder

Azure Linux App Service

  1. Remote into the App Service with SSH.
  2. Navigate to /home/site/wwwroot/. Create a folder for the AppOptics Java APM Agent, example “appoptics”
  3. Follow the instructions in Linux to install the agent

Maven

The AppOptics Agent jar is available on public Maven repository with group ID com.appoptics.agent.java and artifact ID appoptics-agent.

Note

The AppOptics agent jar artifact should NOT be included as a part of the project dependencies directly. Rather, this artifact should be integrated into the build process by using extra step such as the copy goal of maven-dependency-plugin.

The AppOptics java agent jar should only be referenced by the java process via the -javaagent argument instead of regular classpath.

An example of using the copy goal of the maven-dependency-plugin in a Maven pom.xml:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>3.1.1</version>
    <executions>
        <execution>
            <id>copy</id>
            <phase>package</phase>
            <goals>
                <goal>copy</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>com.appoptics.agent.java</groupId>
                        <artifactId>appoptics-agent</artifactId>
                        <version>${appoptics.agent.version}</version>
                        <type>jar</type>
                        <overWrite>true</overWrite>
                        <outputDirectory>${project.basedir}/agent</outputDirectory>
                        <destFileName>appoptics-agent.jar</destFileName>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
    </executions>
</plugin>

Enabling the Agent

After installing on the system, please follow steps below to enable agent monitoring for various common application servers. You might also want to configure the agent tailored to your monitoring needs.

Enabling the Agent on Linux

Tomcat (standalone distribution or apt-get installation)

  1. Find the directory containing your tomcat installation, e.g., /usr/local/apache-tomcat-7.0.25. The installation location will vary based on platform, tomcat version, and your system configuration.
  2. Edit or create /path/to/tomcat/bin/setenv.sh, or in some distributions, /path/to/tomcat/bin/catalina.sh.
  3. Add the following JAVA_OPTS environment variable setting to load the AppOptics Java Agent.
JAVA_OPTS="$JAVA_OPTS -javaagent:<agent installation path>/appoptics-agent.jar"
  1. Restart tomcat by using the shutdown.sh and startup.sh script included with tomcat.
  2. If you are managing your tomcat installation using jsvc, you’ll need to make sure that the above -javaagent parameter is passed in.

Tomcat (yum installation)

  1. Edit tomcat configuration file, for example /etc/tomcat8/tomcat8.conf.
  2. Set JAVA_OPTS environment variable to load the AppOptics Java Agent. Ensure tomcat user has at least read access to BOTH the agent jar and its parent directory(ies)
JAVA_OPTS="-javaagent:<agent installation path>/appoptics-agent.jar"
  1. Restart Tomcat.

Jetty

  1. Edit or create /etc/default/jetty.
  2. Add the following JAVA_OPTIONS environment variable setting to load the AppOptics Java Agent.
JAVA_OPTIONS="-javaagent:<agent installation path>/appoptics-agent.jar"
  1. Restart Jetty. The jetty.sh script included with the jetty distribution will parse the /etc/default/jetty file and add the -javaagent command line option to the jvm.

Glassfish

  1. Find the directory containing your glassfish installation, e.g., /usr/local/glassfish-3.1.2.
  2. Locate domain.xml, which by default is in /path/to/glassfish/domains/domain1/config/.
  3. Scroll through the file and locate the <jvm-options> tags.
  4. Add a new <jvm-options> tag before any existing ones as shown.
<jvm-options>-javaagent:<agent installation path>/appoptics-agent.jar</jvm-options>
  1. Restart Glassfish.

Wildfly (domain mode)

  1. Edit the Wildfly domain configuration, e.g., /usr/local/wildfly-10.0.0.Final/domain/configuration/domain.xml.
  2. Modify/Add jvm-options node with AppOptics Java Agent jar location as the value
<server-groups>
    <server-group name="main-server-group" profile="full">
        <jvm name="default">
            ...
            <jvm-options>
                <option value="-javaagent:<agent installation path>/appoptics-agent.jar"/>
            </jvm-options>
        </jvm>
    ...
</server-groups>
  1. Restart Wildfly in domain mode.

Wildfly (standalone mode)

  1. Find the directory containing your Wildfly installation, e.g., /usr/local/wildfly-10.0.0.Final.
  2. Edit your running config, which by default is at /path/to/wildfly/bin/standalone.conf.
  3. Append the following JAVA_OPTS environment variable setting, which loads the AppOptics Java Agent.
JAVA_OPTS="$JAVA_OPTS -javaagent:<agent installation path>/appoptics-agent.jar"
  1. Restart Wildfly in standalone mode.

JBoss 7.x (domain mode)

  1. Edit the jboss domain configuration, e.g., /usr/local/jboss-7.1.1/domain/configuration/domain.xml.
  2. Modify/Add jvm-options node with AppOptics Java Agent jar location as the value
<server-groups>
    <server-group name="main-server-group" profile="full">
        <jvm name="default">
            ...
            <jvm-options>
                <option value="-javaagent:<agent installation path>/appoptics-agent.jar"/>
            </jvm-options>
        </jvm>
    ...
</server-groups>
  1. Restart JBoss in domain mode.

JBoss 7.x (standalone mode)

  1. Find the directory containing your jboss installation, e.g., /usr/local/jboss-as-7.1.0.Final.
  2. Edit your running config, which by default is at /path/to/jboss/bin/standalone.conf.
  3. Append the JAVA_OPTS environment variable setting, which loads the AppOptics Java Agent.
JAVA_OPTS="$JAVA_OPTS -javaagent:<agent installation path>/appoptics-agent.jar"
  1. Restart JBoss in standalone mode.

JBoss 4.x - 6.x

  1. Find the directory containing your jboss installation, e.g., /usr/local/jboss-6.0.0.Final. The installation location will vary based on platform, jboss version, and your system configuration.
  2. Edit your running config, which by default is at /path/to/jboss/bin/run.conf.
  3. Append the following JAVA_OPTS environment variable setting, which loads the AppOptics Java Agent.
JAVA_OPTS="$JAVA_OPTS -javaagent:<agent installation path>/appoptics-agent.jar"
  1. Restart your jboss server using the shutdown.sh and run.sh scripts included with jboss.

Resin 4.0.x

  1. Find the directory containing your resin installation, e.g., /usr/local/resin-4.0.27. The installation location will vary based on platform, resin version, and your specific system configuration.
  2. Edit resin.properties, which by default is at /path/to/resin/conf/resin.properties.
  3. Add or edit a jvm_args entry as shown.
jvm_args : -javaagent:<agent installation path>/appoptics-agent.jar
  1. Restart Resin.

Resin 3.1.x

  1. Find the directory containing your resin installation, e.g., /usr/local/resin-3.1.12. The installation location will vary based on platform, resin version, and your specific system configuration.
  2. Edit resin.conf, which by default is at /path/to/resin/conf/resin.conf.
  3. Add a <jvm-arg> tag specifying the -javaagent parameter as follows.
<jvm-arg>-javaagent:<agent installation path>/appoptics-agent.jar</jvm-arg>
  1. Restart Resin.

WebLogic - admin console for managed servers

  1. Start the weblogic server administration console.
  2. Click the server that should have the AppOptics Java Agent installed on it.
  3. Click the ‘server start’ tab, locate the arguments field, and append the following.
-javaagent:<agent installation path>/appoptics-agent.jar
  1. Save your changes.
  2. Restart the configured application server.

WebLogic - modify config.xml for managed servers

  1. Locate the domain config file for the weblogic domain. It should be at ${DOMAINS_HOME}/${DOMAIN}/config/config.xml.
  2. In the file, locate the managed server nodes that should have the AppOptics Java Agent installed on them.
  3. Under the server node, append the following to the server-start=>arguments node, adding the argument node if necessary.
-javaagent:<agent installation path>/appoptics-agent.jar
  1. Save the file.
  2. Restart the configured application server.

WebLogic - modify setDomainEnv.cmd for single server domain (AdminServer only)

  1. Locate the domain environment script of the weblogic domain that should have the AppOptics Java Agent installed on it. It should be at ${DOMAINS_HOME}/${DOMAIN}/bin/setDomainEnv.cmd.
  2. Near the top of the file add the following line.
export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:<agent installation path>/appoptics-agent.jar"
  1. Restart the domain.

WebSphere - admin console

  1. Start the websphere application server admin console.
  2. From the left panel, navigate to servers > server types > websphere application servers.
  3. Click on the application server that should have the AppOptics java agent installed on it.
  4. In the configuration tab, expand ‘java and process management’ under ‘server infrastructure’.
  5. Click ‘process definition’.
  6. Click ‘java virtual machine’ under ‘additional properties’.
  7. In the configuration tab, locate the generic jvm argument field, and append the following. Note that the path cannot contain any spaces, replace them with ‘~’.
-javaagent:<agent installation path>/appoptics-agent.jar
  1. Apply and save the changes.
  2. Restart the configured application server.

WebSphere - server.xml

  1. Locate the server config file of the websphere application server that should have AppOptics Java Agent installed on it. It should be at ${PROFILE_HOME}\config\cells\ ${CELL}\nodes\${NODE}\servers\${SERVER}\server.xml.
  2. Locate xml node process: Server/processDefinitions/jvmEntries. Append the following to attribute genericJvmArguments. Note that the path cannot contain any spaces, replace them with ‘~’.
-javaagent:<agent installation path>/appoptics-agent.jar
  1. Restart the configured application server.

WebSphere Liberty Profile

  1. Add/edit jvm.options file for the target server. For example at <WebSphere installation directory>/usr/servers/defaultServer/jvm.options.
  2. Add a line as below
-javaagent:<agent installation path>/appoptics-agent.jar
  1. Restart the configured application server.

Play 2.3+ development mode

For instructions on installing the Java Agent, see the activator/sbt instructions.

Play 2.3+ production mode

Running ‘activator dist’ generates a startup script, and the option to add on our Java Agent is pretty similar to previous versions.

bin/<startup script> -J-javaagent:<agent installation path>/appoptics-agent.jar

Play 2.0 - 2.2 development mode

Add the following line just before the java command in the play build script. Then start your play project using ‘play run’.

JAVA_OPTS="$JAVA_OPTS -javaagent:<agent installation path>/appoptics-agent.jar"

Play 2.2

The ‘play start’ command does not support the javaagent option. Instead, start the play project using the script in the bin folder of /path/to/project with the javaagent argument.

bin/<startup script> -J-javaagent:<agent installation path>/appoptics-agent.jar

Play 2.0 - 2.1 production mode

The ‘play start’ command does not support the javaagent option. Instead, start the play project using the script in the bin folder of /path/to/project with the javaagent argument.

bin/<startup script> -javaagent:<agent installation path>/appoptics-agent.jar

Play 1.1.1

Start the play project using the command ‘play run’ with the javaagent argument.

play run myproject -javaagent:<agent installation path>/appoptics-agent.jar

Spray-can development mode

Spray-can is the http connector/server of the spray framework. It can be run via activator/sbt in developer mode or as a plain jar in production mode. For instructions on installing the Java Agent, see the activator/sbt instructions.

Spray-can production mode

To add our Java Agent when running in production mode, simply append the jvm option -javaagent:<agent installation path>/appoptics-agent.jar to the spray java process. For example, if it’s run on a fat jar:

java -javaagent:<agent installation path>/appoptics-agent.jar -jar your-spray-jar.jar

Linux standalone Java application

To add our Java Agent to standalone Java application (for example: gRPC server, Spring Boot embedded web server etc), simply add the jvm option -javaagent:<agent installation path>/appoptics-agent.jar when starting the Java process. For example:

java -javaagent:<agent installation path>/appoptics-agent.jar -jar your-standalone-app.jar

Linux Activator/sbt

Activator and sbt are platforms to build and start java/scala apps, usually for development, not production. Some frameworks such as play, spray use sbt/activator by default.

Sbt

  • To add the Java Agent to all sbt projects when running in development mode, i.e., ‘sbt run’, add the following line to the end of sbt/install/directory/conf/sbtopts.
  • To add the Java Agent to a specific sbt project, add the following line to .sbtopts in your sbt project folder, creating that file if necessary.
-J-javaagent:<agent installation path>/appoptics-agent.jar

Activator

  • To add the Java Agent to all activator projects when running in development mode, i.e., ‘activator run’, add the following line to user\home\directory\.activator\activatorconfig.txt.
  • To add the Java Agent to a specific version only, add the following line to the end of user\home\directory\.activator\version\activatorconfig.txt.
  • To add the Java Agent to a specific activator project, add the following line to environment variable ACTIVATOR_OPTS, SBT_OPTS or JAVA_OPTS.
-javaagent:<agent installation path>/appoptics-agent.jar

Grails

Grails versions 1.0-1.3 are only partially supported: only the top layer is reported, filters and controller profiles are not reported.

  1. Modify your grails-app/conf/BuildConfig.groovy file and add a line similar to the one below, modifying it to suit your environment.
grails.tomcat.jvmArgs = ["-javaagent:<agent installation path>/appoptics-agent.jar"]

Azure App Service

  1. From the Azure Portal, select the App Service, then Settings > Configuration
  2. For Tomcat, add/modify CATALINA_OPTS. For other services, add/modify JAVA_OPTS to include jvm args as below
-javaagent:/home/site/wwwroot/appoptics/appoptics-agent.jar
  1. Restart the App Service

Enabling the Agent on Windows

Tomcat as service or with Tomcat monitor application

  1. Start the tomcat configuration application by start > apache tomcat > configure tomcat. Alternately, start the monitor application via command line, an example for tomcat 9 (see the tomcat 9 windows service reference for details):

    C:\apache-tomcat-9\bin>tomcat9w.exe
    
  2. Go to the ‘java’ tab and locate the ‘java options’ text box.

  3. Append the following line.

-javaagent:C:\Program Files\AppOptics\APM\java\appoptics-agent.jar
  1. Go to the ‘general’ tab and restart the tomcat server.

Alternately, the java option can be set via command line using the service application’s //US// and --JvmOptions arguments to update the service parameters. An example for tomcat 9 (see the tomcat 9 windows service reference for details):

C:\apache-tomcat-9\bin>tomcat9.exe //US//Tomcat9 --JvmOptions=“-javaagent:C:\Program Files\AppOptics\APM\java\appoptics-agent.jar”
  1. Restart Tomcat service.

Tomcat by start.bat/catalina.bat or other scripts

  1. Locate the tomcat installation directory.
  2. Go to the \path\to\tomcat\bin and edit or create setenv.bat.
  3. Append the following line.
set JAVA_OPTS=%JAVA_OPTS% -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"
  1. Restart Tomcat.

Jetty

Add a javaagent option to the startup command.

java -javaagent:"C:\Progra~1\AppOptics\APM\java\appoptics-agent.jar" -jar start.jar

Glassfish

  1. Find the directory containing your glassfish installation.
  2. Locate domain.xml, which by default is at \path\to\glassfish\domains\domain1\config\domain.xml.
  3. In the file, locate the tags.
  4. Add a new tag before any existing tags.
<jvm-options>-javaagent:C:\Program Files\AppOptics\APM\java\appoptics-agent.jar</jvm-options>
  1. Restart Glassfish.

Wildfly (domain mode)

  1. Edit the Wildfly domain configuration in \path\to\wildfly\domain\configuration\domain.xml.
  2. Modify/Add jvm-options node with AppOptics Java Agent jar location as the value
<server-groups>
    <server-group name="main-server-group" profile="full">
        <jvm name="default">
            ...
            <jvm-options>
                <option value="-javaagent:C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"/>
            </jvm-options>
        </jvm>
    ...
</server-groups>
  1. Restart Wildfly in domain mode.

Wildfly (standalone mode)

  1. Find the directory containing your Wildfly installation.
  2. Edit your running config, which by default is at /path/to/wildfly/bin/standalone.conf.
  3. Append the following JAVA_OPTS environment variable setting, which loads the AppOptics Java Agent.
JAVA_OPTS="$JAVA_OPTS -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar""
  1. Restart Wildfly in standalone mode.

JBoss 7.x (domain mode)

  1. Edit the JBoss domain configuration in \path\to\jboss\domain\configuration\domain.xml.
  2. Modify/Add jvm-options node with AppOptics Java Agent jar location as the value
<server-groups>
    <server-group name="main-server-group" profile="full">
        <jvm name="default">
            ...
            <jvm-options>
                <option value="-javaagent:C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"/>
            </jvm-options>
        </jvm>
    ...
</server-groups>
  1. Restart JBoss in domain mode.

JBoss 7.x (standalone mode)

Find the directory containing your JBoss installation.

  1. Edit \path\to\jboss\bin\standalone.conf.bat.
  2. Locate the last line of ‘set JAVA_OPTS’, and append a new line as shown.
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar""
  1. Restart JBoss in standalone mode.

JBoss 5.x - 6.x

  1. Find the directory containing your jboss installation.
  2. Edit \path\to\jboss\bin\run.conf.bat.
  3. Locate the last line of ‘set JAVA_OPTS’, and append a new line as shown; note that jboss 5.x doesn’t allow spaces in javaagent path, so C:\Progra~1 instead.
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar""
  1. Restart JBoss.

JBoss 4.x

  1. Find the directory containing your jboss installation.
  2. Edit \path\to\jboss\bin\run.bat.
  3. Locate the last line of ‘set JAVA_OPTS’, and append a new line as shown.
set JAVA_OPTS=%JAVA_OPTS% -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"
  1. Restart JBoss.

Resin 4.0.x

  1. Find the directory containing your resin installation.
  2. Edit \path\to\resin\resin.properties.
  3. Add or edit a jvm_args entry as shown.
jvm_args : -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"
  1. Restart Resin.

Resin 3.1.x

  1. Find the directory containing your resin installation.
  2. Edit \path\to\resin\resin.conf.
  3. Add a element after the existing element specifying the -javaagent parameter. Note that resin 3.1.x doesn’t allow space within the javaagent path, so use C:\Progra~1 instead.
<jvm-arg>-javaagent:C:\Progra~1\AppOptics\APM\java\appoptics-agent.jar</jvm-arg>
  1. Restart Resin.

WebLogic - admin console for managed servers

  1. Start the weblogic server administration console.
  2. Click the server that should have the AppOptics Java Agent installed on it.
  3. Click the ‘server start’ tab, locate the arguments field, and append the following.
-javaagent:C:\Program Files\AppOptics\APM\java\appoptics-agent.jar
  1. Save your changes.
  2. Restart the configured application server.

WebLogic - modify config.xml for managed servers

  1. Locate the domain config file for the weblogic domain. It should be at ${DOMAINS_HOME}/${DOMAIN}/config/config.xml.
  2. In the file, locate the managed server nodes that should have the AppOptics Java Agent installed on them.
  3. Under the server node, append the following to the server-start=>arguments node, adding the argument node if necessary.
-javaagent:C:\Program Files\AppOptics\APM\java\appoptics-agent.jar
  1. Save the file.
  2. Restart the configured application server.

WebLogic - modify setDomainEnv.cmd for single server domain (AdminServer only)

  1. Locate the domain environment script of the weblogic domain that should have the AppOptics Java Agent installed on it. It should be at {DOMAINS_HOME}/{DOMAIN}/bin/setDomainEnv.cmd.
  2. Near the top of the file add the following line.
set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"
  1. Restart the domain.

WebSphere - admin console

  1. Start the websphere application server admin console.
  2. From the left panel, navigate to servers > server types > websphere application servers.
  3. Click on the application server that should have the AppOptics java agent installed on it.
  4. In the configuration tab, expand ‘java and process management’ under ‘server infrastructure’.
  5. Click ‘process definition’.
  6. Click ‘java virtual machine’ under ‘additional properties’.
  7. In the configuration tab, locate the generic jvm argument field, and append the following. Note that the path cannot contain any spaces, replace them with ‘~’.
-javaagent:C:\Progra~1\AppOptics\APM\java\appoptics-agent.jar
  1. Apply and save the changes.
  2. Restart the configured application server.

WebSphere - server.xml

  1. Locate the server config file of the websphere application server that should have AppOptics Java Agent installed on it. It should be at ${PROFILE_HOME}\config\cells\ ${CELL}\nodes\${NODE}\servers\${SERVER}\server.xml.
  2. Locate xml node process: Server/processDefinitions/jvmEntries. Append the following to attribute genericJvmArguments. Note that the path cannot contain any spaces, replace them with ‘~’.
-javaagent:C:\Progra~1\AppOptics\APM\java\appoptics-agent.jar

WebSphere Liberty Profile

  1. Add/edit jvm.options file for the target server. For example at <WebSphere installation directory>\usr\servers\defaultServer\jvm.options.
  2. Add a line as below
-javaagent:C:\Progra~1\AppOptics\APM\java\appoptics-agent.jar
  1. Restart the configured application server.

Play 2.3+ development mode

For instructions on installing the Java Agent, see the Activator/sbt instructions.

Play 2.3+ production mode

Running ‘activator dist’ generates a startup script, and the option to add on our Java Agent is pretty similar to previous versions.

Note

Workaround required: The windows startup script needs a work around to overcome a known issue for activator related to length limitation with cmd.exe command line strings. bin/<startup script> -J-javaagent:C:\PROGRA~1\AppOptics\APM\java\appoptics-agent.jar

Play 2.0 - 2.2 development mode

Add the following line just before the java command in the play build script. Then start your play project using ‘play run’.

set JAVA_OPTS=%JAVA_OPTS% -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"

Play 2.2

The ‘play start’ command does not support the javaagent option. Instead, start the play project using the script in the bin folder of /path/to/project with the javaagent argument.

bin\<startup script> -J-javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"

Play 2.0 - 2.1 production mode

The ‘play start’ command does not support the javaagent option. Instead, start the play project using the script in the bin folder of /path/to/project with the javaagent argument.

bin\<startup script> -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"

Play 1.1.1

Start the play project using the command ‘play run’ with the javaagent argument.

play run myproject -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"

Spray-can development mode

Spray-can is the http connector/server of the spray framework, like netty for play. It can be run via sbt/activator in dev mode, or run as a plain jar in production mode. For instructions on installing the java agent, see the Activator/sbt instructions.

Spray-can production mode

To add our Java Agent when running in production mode, simply append the jvm option -javaagent:/path/to/java/agent.jar to the spray java process. For example, if it’s run on a fat jar:

java -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar" -jar your-spray-jar.jar

Windows standalone Java application

To add our Java Agent to standalone Java application (for example: gRPC server, Spring Boot embedded web server etc), simply add the jvm option -javaagent:<agent installation path>/appoptics-agent.jar when starting the Java process. For example:

java -javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar" -jar your-standalone-app.jar

Windows Activator/sbt

Activator and sbt are platforms to build and start java/scala apps, usually for development, not production. Some frameworks such as play, spray use sbt/activator by default.

Activator

  • To add the Java Agent to all activator projects when running in development mode, i.e., started using activator run, add the following line to the end of user\home\directory\.activator\activatorconfig.txt, creating the file if necessary.
  • To add the Java Agent to a specific version only, add the following line to user\home\directory\.activator\version\activatorconfig.txt.
  • To add the Java Agent to a specific sbt project, add the following line to environment variable CFG_OPTS, ACTIVATOR_OPTS, SBT_OPTS or JAVA_OPTS.
-javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"

Sbt

  • To add the Java Agent to all sbt projects when running in development mode, i.e., started using sbt run, add the following line to the end of sbt installation directory\conf\sbtconfig.txt.
  • To add the Java Agent to a specific sbt project, add the line to environment variable SBT_OPTS or JAVA_OPTS.
-javaagent:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar"

Azure App Service

  1. From the Azure Portal, select the App Service, then Settings > Configuration
  2. For Tomcat, add/modify CATALINA_OPTS. For other services, add/modify JAVA_OPTS to include jvm args as below
-javaagent:/home/site/wwwroot/AppOptics/appoptics-agent.jar=service_key=<your service key>,log_file=appoptics-runtime.log
  1. Restart the App Service

Note

Our agent by default writes logs to the stdout and stderr streams. However, the logs might be lost for Windows application servers that do not redirect those streams to any file (for example Tomcat). Our example above redirects logs to the file “appoptics-runtime.log”. For more options, please follow the instructions in the Detailed Logging Configuration section.

Troubleshooting

After installing the agent if traces and metric data do not appear in the AppOptics dashboard, please review the Troubleshooting page for tips on how to resolve.

Diagnostics

Connectivity diagnostic tool can be run using the same APM agent jar installed. For example:

java -cp "c:\Program Files\AppOptics\APM\java\appoptics-agent.jar" com.appoptics.diagnostic.DiagnosticTools

There are also several optional parameters available:

  • service_key : Service key to be used for the diagnostic tool. By default it uses the current service key configured in the host.
  • timeout : Max time to wait for the diagnostic tool to finish in milliseconds. By default it waits for 5 seconds.
  • log_file : File location to print the diagnostic tool logs to, could either be relative (to current directory) or absolute path. By default it outputs to console.
  • config : Java agent json config file for running the diagnostic tool. By default it uses the config file javaagent.json within the same directory as the APM agent jar.

For example:

java -cp "c:\Program Files\AppOptics\APM\java\appoptics-agent.jar" com.appoptics.diagnostic.DiagnosticTools timeout=10000 log_file=appoptics-diagnostics.log

To enable more verbose logging for the diagnostic tool, simply change the javaagent.json’s agent.logging level to debug or trace. Please remember to revert the change after finishing all the diagnostics.

If diagnostic tool did not find any problem, it should print at the end:

INFO [AppOptics] [OK] message: Diagnostics successful

The diagnostic tool provides exit code as below:

Exit Status Code Name Description
0 OK Diagnostics successful
101 UNKNOWN_ERROR Unexpected error. See error message for details
102 INVALID_FORMAT_ARGUMENT Argument passed to the diagnostic tool is not in valid format. For example the service key is too short. See error message for details
103 INVALID_ARGUMENTS Argument passed to the diagnostic tool is incorrect. For example using argument name not recognized by the diagnostic. See error message for details
104 INVALID_SERVICE_KEY Service key is rejected by AppOptics server
105 CONNECTION_FAILURE Failed to connect to the AppOptics server within the timeout limit(default to 5 seconds). Most connection problem should get this status code.
106 TRY_LATER AppOptics server rejected the diagnostic request with status TRY_LATER
107 LIMIT_EXCEEDED AppOptics server rejected the diagnostic request with status LIMIT_EXCEEDED
108 CONNECTION_FAILURE_FATAL Fatal connection problem to AppOptics server. For example SSL cert specified by APPOTPICS_TRUSTEDPATH is not found. See error message for details

Log File Locations

The Java Agent writes to System.err for warning and fatal messages, and to System.out for lower severity messages such as info and debug. For most application servers, those two streams will be directed to standard logging files - for example catalina.out for tomcat.

Please take note that all logging messages from the agent are preceded by the tag [AppOptics]. By default only messages with verbosity info or higher (warning, fatal etc.) are reported. To see debugging messages, please set the logging level to debug or trace. More details in Set Logging Level.