Installation (legacy agent)

The following content pertains to installation for the legacy AppOptics Java Agent.

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.

Get the agent jar

Linux

1. Create and navigate to the desired agent installation location
2. Download agent installation script using the command: curl -sSO https://files.appoptics.com/appoptics-java.sh
3. Execute the installation script using the command: sh 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. For command line installation, please refer to the section below

Command Line Install

To automate the installation of the AppOptics Java Agent, the agent can be installed via the command line.

1. Create a file called conf.inf with the following contents, and place it in the same directory as your installer.

   [Setup]
   service_key=<your service key>

2. Run following command:

   # to install the Java agent via the command line
   # square brackets indicate an optional parameter
   # the pipe character separates multiple choices within an option
   JavaAgent_Setup.exe [/SILENT | /VERYSILENT] /LOADINF="conf.inf"

• /SILENT – this flag instructs the installer to be silent, the installation progress window is displayed.
• /VERYSILENT – this flag instructs the installer to be very silent, the install progress window is not displayed.

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
• https://files.appoptics.com/java/latest/appoptics-agent.jar
• https://files.appoptics.com/java/latest/javaagent.json

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.

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
• Enabling the Agent on Windows

Enabling the Agent on Linux

• Tomcat (standalone distribution or apt-get installation)
• Tomcat (yum installation)
• Jetty
• Glassfish
• Wildfly (domain mode)
• Wildfly (standalone mode)
• JBoss 7.x (domain mode)
• JBoss 7.x (standalone mode)
• JBoss 4.x - 6.x
• Resin 4.0.x
• Resin 3.1.x
• WebLogic - admin console for managed servers
• WebLogic - modify config.xml for managed servers
• WebLogic - modify setDomainEnv.cmd for single server domain (AdminServer only)
• WebSphere - admin console
• WebSphere - server.xml
• WebSphere Liberty Profile
• Play 2.3+ development mode
• Play 2.3+ production mode
• Play 2.0 - 2.2 development mode
• Play 2.2
• Play 2.0 - 2.1 production mode
• Play 1.1.1
• Spray-can development mode
• Spray-can production mode
• Linux standalone Java application
• Linux Activator/sbt
• Sbt
• Activator
• Grails
• Azure App Service

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"

4. Restart tomcat by using the shutdown.sh and startup.sh script included with tomcat.
5. 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"

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

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

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

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

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

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

4. 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"

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

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

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

4. Save your changes.
5. 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

4. Save the file.
5. 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"

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

8. Apply and save the changes.
9. 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

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

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

3. Restart the App Service

Enabling the Agent on Windows

• Tomcat as service or with Tomcat monitor application
• Tomcat by start.bat/catalina.bat or other scripts
• Jetty
• Glassfish
• Wildfly (domain mode)
• Wildfly (standalone mode)
• JBoss 7.x (domain mode)
• JBoss 7.x (standalone mode)
• JBoss 5.x - 6.x
• JBoss 4.x
• Resin 4.0.x
• Resin 3.1.x
• WebLogic - admin console for managed servers
• WebLogic - modify config.xml for managed servers
• WebLogic - modify setDomainEnv.cmd for single server domain (AdminServer only)
• WebSphere - admin console
• WebSphere - server.xml
• WebSphere Liberty Profile
• Play 2.3+ development mode
• Play 2.3+ production mode
• Play 2.0 - 2.2 development mode
• Play 2.2
• Play 2.0 - 2.1 production mode
• Play 1.1.1
• Spray-can development mode
• Spray-can production mode
• Windows standalone Java application
• Windows Activator/sbt
• Activator
• Sbt
• Azure App Service

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

4. 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"

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

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

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

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

3. Append the following JAVA_OPTS environment variable setting, which loads the AppOptics Java Agent.

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

   Wildfly 8.x.x does not allow space within the javaagent path; use the short name path instead. For example, use C:\Progra~1 to reference the Program Files folder

   set "JAVA_OPTS=%JAVA_OPTS% -javaagent:"C:\Progra~1\AppOptics\APM\java\appoptics-agent.jar""

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

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

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

4. 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"

4. 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"

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

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

4. Save your changes.
5. 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

4. Save the file.
5. 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"

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

8. Apply and save the changes.
9. 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

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

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

3. Restart the App Service

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 Java 6:

java -Xbootclasspath/a:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar" com.appoptics.diagnostic.DiagnosticTools

For Java 7+:

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, to set a timeout of 10 seconds and save the diagnostic tool logs to a file named appoptics-diagnostics.log for users with Java 7+, run the following command:

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

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.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.