Install and load the Java Library

Before you start

Verify the following to ensure the library can collect and transmit data:

• The platform where your APM library will be installed is supported.

• Your application components are supported by the library.

• Your firewall configuration permits TCP/HTTPS/TLS outbound connections to apm.collector.xx-yy.cloud.solarwinds.com (where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs) using port 443. See Firewall or access control requirements.

  If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Do not run other APM libraries alongside the SolarWinds Observability Java Library. Remove other APM libraries and agents from your Java application before using the SolarWinds Observability Java Library.

Install the library JAR

Install on Linux

1. Navigate to the desired library installation location.

2. Download the library installation script using the following command:

   curl -sSO https://agent-binaries.cloud.solarwinds.com/apm/java/latest/solarwinds-apm-agent.jar

3. Set the Service key in the config file or as an environment variable available to the application process. You can also define the environment variable inside the application startup script.

   For example, to set it for an application to be started in the current or child shell session, run the following command:

   export SW_APM_SERVICE_KEY=YourServiceKey

   Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

   The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

   The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

Now that the library is installed, enable the library for monitoring.

Install on Windows

1. Navigate to the desired library installation location.

2. Download the https://agent-binaries.cloud.solarwinds.com/apm/java/latest/solarwinds-apm-agent.jar library JAR file.

3. Set the Service key in the config file or as an environment variable available to the application process. The environment variable can also be set at different scopes or defined inside the application startup script. See about_Environment_Variables in Microsoft's PowerShell documentation.

   For example, to set it for an application to be started in the current or child shell session, run the following command:

   $Env:SW_APM_SERVICE_KEY="YourServiceKey"

   Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

   The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

   The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

Now that the library is installed, enable the library for monitoring.

Install on the Azure Windows App Service

1. Remote into the Azure App Service. For information about remoting into Azure App Service with Kudo Shell and CMD, see Kudo Diagnostic Console and Working with Files in Azure App Service in the Microsoft documentation for Azure.

2. Navigate to D:\home\site\wwwroot. Create a folder for the Java Library, for example SolarWinds

3. Download the library JAR and JSON config files to the library's folder:

   https://agent-binaries.cloud.solarwinds.com/apm/java/latest/solarwinds-apm-agent.jar

4. Open the Azure App Service's management console and click Configure > Application Settings. Add a new Application Setting for the Service key environment variable environment variable:

   • For the SW_APM_SERVICE_KEY environment variable, set the value to the Service key you are using to identify your account and the service being instrumented.

     The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

     The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

   • For the SW_APM_COLLECTOR environment variable, set the value to apm.collector.xx-yy.cloud.solarwinds.com (where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs).

Now that the library is installed, enable the library for monitoring.

Install on the Azure Linux App Service

1. Open an SSH session to your App Service.
2. Navigate to /home/site/wwwroot/. Create a folder for the Java Library, for example SolarWinds.
3. Follow the instructions to Install on Linux .

Load the library

After the library is installed on the system, the library must be loaded into your application. To load the library, add the -javaagent:<library installation path>/solarwinds-apm-agent.jar parameter to the JVM startup command. For instructions on how to add the parameter for your specific application server, see one of the following:

• Load the library (Linux web servers)
• Load the library (Windows web servers)

To tailor the library to your monitoring needs, see Configure the Java Library.

Load the library (Linux web servers)

• Tomcat (standalone distribution or apt-get installation)
• Tomcat (yum installation)
• Jetty
• GlassFish
• WildFly (domain mode)
• WildFly (standalone mode)
• WebLogic (using the administration console for managed servers)
• WebLogic (using config.xml for managed servers)
• WebLogic (using setDomainEnv.cmd for a single server domain - AdminServer only)
• Open Liberty
• Play 2.4+ (development mode)
• Play 2.4+ (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 Apache Tomcat installation. The installation location will vary based on platform, Tomcat version, and your system configuration. For example, Tomcat version 7.0.25 installation is often located at/usr/local/apache-tomcat-7.0.25.

2. Open the setenv.shscript located in the bin folder of the Tomcat installation directory. If one does not exist, create a new setenv.sh file. For some distributions, the environment variables are defined in catalina.sh instead of setenv.sh.

3. Add a JAVA_OPTS environment variable with the -javaagent parameter defined:

   JAVA_OPTS="$JAVA_OPTS -javaagent:<library installation path>/solarwinds-apm-agent.jar"

4. Save the file and run the shutdown.sh and startup.sh scripts to restart Tomcat.

5. If you are managing your Tomcat installation using jsvc, make sure that the -javaagent parameter above is passed in.

Tomcat (yum installation)

1. Open the Tomcat config file. For Tomcat 8 installations, it is often located at /etc/tomcat8/tomcat8.conf.

2. Set the JAVA_OPTS environment variable with the -javaagent parameter as the value.

   The Tomcat user must have read access to both solarwinds-apm-agent.jar and its parent directories.

   JAVA_OPTS="-javaagent:<library installation path>/solarwinds-apm-agent.jar"

3. Save the file and run the shutdown.sh and startup.sh scripts to restart Tomcat.

Jetty

1. Open the Jetty config file at /etc/default/jetty. If this file does not exist, create a file at this path.

2. Add the JAVA_OPTIONS environment variable with the -javaagent parameter as the value:

   JAVA_OPTIONS="-javaagent:<library installation path>/solarwinds-apm-agent.jar"

3. Save the file and restart Jetty. The jetty.sh script included with the Jetty distribution parses the /etc/default/jetty file and adds the -javaagent command line option to the JVM.

GlassFish

1. Find the directory containing your GlassFish installation.

2. Open domain.xml, located by default in the domains/domain1/config/ folder of the GlassFish installation directory.

3. Find the first <jvm-options> tag.

4. Add a new <jvm-options> tag before the first <jvm-options> tag, with the -javaagent parameter as the value:

   <jvm-options>-javaagent:<library installation path>/solarwinds-apm-agent.jar</jvm-options>

5. Save the file and restart GlassFish.

WildFly (domain mode)

These instructions might also work for JBoss, but they have not been explicitly tested.

1. Open the WildFly domain config file. For WildFly 10.0.0 installations, it is often located at /usr/local/wildfly-10.0.0.Final/domain/configuration/domain.xml.

2. Modify an existing or add a new jvm-options node with the value attribute defined as the -javaagent parameter.

   <server-groups>
     <server-group name="main-server-group" profile="full">
       <jvm name="default">
         ...
         <jvm-options>
           <option value="-javaagent:<library installation path>/solarwinds-apm-agent.jar"/>
         </jvm-options>
       </jvm>
       ...
   </server-groups>

3. Save the file and restart WildFly in domain mode.

WildFly (standalone mode)

These instructions might also work for JBoss, but they have not been explicitly tested.

1. Find the directory containing your WildFly installation. For WildFly 10.0.0 installations, it is often located at /usr/local/wildfly-10.0.0.Final.

2. Open the standalone.conf running config located in the bin folder of the WildFly installation directory.

3. Add the JAVA_OPTS environment variable setting with the -javaagent parameter as the value.

   JAVA_OPTS="$JAVA_OPTS -javaagent:<library installation path>/solarwinds-apm-agent.jar"

4. Save the file and restart WildFly in standalone mode.

WebLogic (using the administration console for managed servers)

These instructions might work for WebLogic, but they have not been explicitly tested.

See Configure startup arguments for Managed Servers in the Oracle WebLogic Server Help Center for how to use the administration console for managed servers.

1. Start the WebLogic Server Administration Console.
2. Click the name of the application server that has the Java Library installed.

3. Click Configuration and then click the Server Start tab.

4. In the arguments field add the -javaagent parameter startup option:

   -javaagent:<library installation path>/solarwinds-apm-agent.jar

5. Save your changes.
6. Restart the configured application server.

WebLogic (using config.xml for managed servers)

These instructions might work for WebLogic, but they have not been explicitly tested.

1. Open the domain config file for the WebLogic domain. It typically is located at ${DOMAINS_HOME}/${DOMAIN}/config/config.xml.
2. Find the managed server nodes that have the Java Library installed.

3. Nested under the managed server node, modify an existing or add a new server-start=>arguments node with the -javaagent parameter value:

   -javaagent:<library installation path>/solarwinds-apm-agent.jar

4. Save the file and restart the configured application server.

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

These instructions might work for WebLogic, but they have not been explicitly tested.

1. Open the domain environment script of the WebLogic domain that has the Java Library installed. It typically is located at ${DOMAINS_HOME}/${DOMAIN}/bin/setDomainEnv.cmd.

2. At the beginning of the file, add the following line to define the -javaagent parameter.

   export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:<library installation path>/solarwinds-apm-agent.jar"

3. Save the file and restart the domain.

Open Liberty

These instructions might also work for Websphere, but they have not been explicitly tested.

1. Open the jvm.options file for the target server. It typically is located in the /usr/servers/defaultServer/ folder in your WebSphere installation directory

2. Add an option defining the -javaagent parameter:

   -javaagent:<library installation path>/solarwinds-apm-agent.jar

3. Save the file and restart the configured application server.

Play 2.4+ (development mode)

Follow the instructions for Linux Activator/sbt to load the Java Library for Play 2.4+ (development mode).

Play 2.4+ (production mode)

The play start command does not support the -javaagent parameter. Instead, use a startup script to start the Play project.

1. Run the command activator dist to generate a startup script.

2. Open the startup script in the bin folder of the project directory.

3. Add the -javaagent parameter to the startup script:

   bin/<startup script> -J-javaagent:<library installation path>/solarwinds-apm-agent.jar

Linux standalone Java application

To load the Java Library to a standalone Java application (for example, on a gRPC server or a Spring Boot embedded web server), add the -javaagent parameter when starting the java process. An example java process is:

java -javaagent:<library installation path>/solarwinds-apm-agent.jar -jar your-standalone-app.jar

Linux Activator/sbt

Activator and sbt are platforms to build and start Java or Scala apps. Apps on the Activator and sbt platforms are typically used for development, not production. Some frameworks, such as Play or spray, use sbt or Activator by default.

sbt

-J-javaagent:<library installation path>/solarwinds-apm-agent.jar

Activator

-javaagent:<library installation path>/solarwinds-apm-agent.jar

Grails

1. Open the grails-app/conf/BuildConfig.groovy file.

2. Add a line similar to the one below, modifying it to suit your environment.

   grails.tomcat.jvmArgs = ["-javaagent:<library installation path>/solarwinds-apm-agent.jar"]

Azure App Service

1. From the Azure Portal, select the App Service.
2. Click Settings > Configuration.

3. For Tomcat, edit CATALINA_OPTS to include the -javaagent parameter. If CATALINA_OPTS does not exist, add a new option with the following argument.

   For other services, edit JAVA_OPTS to include the -javaagent parameter. If JAVA_OPTS does not exist, add the option with the following argument.

   -javaagent:/home/site/wwwroot/SolarWinds/solarwinds-apm-agent.jar

4. Restart the App Service.

Load the library (Windows web servers)

• Tomcat as a service or with the Tomcat monitor application
• Tomcat (with start.bat, catalina.bat, or other scripts)
• Jetty
• GlassFish
• WildFly (domain mode)
• WildFly (standalone mode)
• WebLogic (admin console for managed servers)
• WebLogic (using config.xml for managed servers)
• WebLogic (using setDomainEnv.cmd for single server domain - AdminServer only)
• Open Liberty
• Play 2.4+ development mode
• Play 2.4+ production mode
• Windows standalone Java application
• Windows Activator/sbt
• Activator
• sbt
• Azure App Service

Tomcat as a service or with the Tomcat monitor application

1. In the command line, set the JVM option using the service application's //US// and --JvmOptions arguments to update the service parameters. An example for Tomcat 9 is:

   C:\apache-tomcat-9\bin>tomcat9.exe //US//Tomcat9 --JvmOptions="-javaagent:<library installation path>\solarwinds-apm-agent.jar"

2. Restart the Tomcat service.

Tomcat (with start.bat, catalina.bat, or other scripts)

1. Locate the Tomcat installation directory.
2. Open the setenv.bat file located in the bin folder of the Tomcat installation directory. If one does not exist, create a setenv.bat file.

3. Add the following line containing the -javaagent parameter.

   set JAVA_OPTS=%JAVA_OPTS% -javaagent:"<library installation path>\solarwinds-apm-agent.jar"

4. Save the file and restart Tomcat.

Jetty

Add the -javaagent parameter to the startup command.

java -javaagent:"<library installation path>\solarwinds-apm-agent.jar" -jar start.jar

GlassFish

1. Find the directory containing your GlassFish installation.

2. Open domain.xml, which is typically located in the \domains\domain1\config\ folder of your GlassFish installation directory.

3. Add a new jvm-options node before any other nodes, with the -javaagent parameter entered as the node's value.

   <jvm-options>-javaagent:<library installation path>\solarwinds-apm-agent.jar</jvm-options>

4. Save the file and restart GlassFish.

WildFly (domain mode)

These instructions might also work for JBoss, but they have not been explicitly tested.

1. Find the directory containing your WildFly installation.

2. Open domain.xml, which is typically located in the \domains\domain\configuration\ folder of your GlassFish installation directory.

3. Find the jvm-options node and add a child option node. The -javaagent parameter is added in the value attribute of the new node. An example of the JVM option defined for a WildFly (domain mode) application is:

   <server-groups>
     <server-group name="main-server-group" profile="full">
       <jvm name="default">
         ...
         <jvm-options>
           <option value="-javaagent:<library installation path>\solarwinds-apm-agent.jar"/>
         </jvm-options>
       </jvm>
       ...
   </server-groups>

4. Save the file and restart WildFly in domain mode.

WildFly (standalone mode)

These instructions might also work for JBoss, but they have not been explicitly tested.

1. Find the directory containing your WildFly installation.

2. Open the standalone.conf.bat running config, typically in the bin folder in the WildFly installation directory.

3. Add the following JAVA_OPTS environment variable setting with the -javaagent parameter.

   set "JAVA_OPTS=%JAVA_OPTS% -javaagent:"<library installation path>\solarwinds-apm-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.

4. Save the file and restart WildFly in standalone mode.

WebLogic (admin console for managed servers)

These instructions might work for WebLogic, but they have not been explicitly tested.

See Configure startup arguments for Managed Servers in the Oracle WebLogic Server Help Center for how to use the administration console for managed servers.

1. Start the WebLogic Server Administration Console.
2. Click the name of the application server that has the Java Library installed.

3. Click Configuration and then click the Server Start tab.

4. In the arguments field add the -javaagent parameter startup option:

   -javaagent:<library installation path>\solarwinds-apm-agent.jar

5. Save your changes.
6. Restart the configured application server.

WebLogic (using config.xml for managed servers)

These instructions might work for WebLogic, but they have not been explicitly tested.

1. Open the domain config file for the WebLogic domain. It typically is located at ${DOMAINS_HOME}/${DOMAIN}/config/config.xml.

2. Find the managed server nodes that have the Java Library installed.

3. Nested under the managed server node, modify an existing or add a new server-start=>arguments node with the following javaagent parameter:

   -javaagent:<library installation path>\solarwinds-apm-agent.jar

4. Save the file and restart the configured application server.

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

These instructions might work for WebLogic, but they have not been explicitly tested.

1. Open the domain environment script of the WebLogic domain that has the Java Library installed. It typically is located at ${DOMAINS_HOME}/${DOMAIN}/bin/setDomainEnv.cmd.

2. At the beginning of the file, add the following line.

   set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:"<library installation path>\solarwinds-apm-agent.jar"

3. Save the file and restart the domain.

Open Liberty

These instructions might also work for Websphere, but they have not been explicitly tested.

1. Open the jvm.options file for the target server. It typically is located in the \usr\servers\defaultServer\ folder in your WebSphere installation directory.

2. Add the -javaagent parameter:

   -javaagent:<library installation path>\solarwinds-apm-agent.jar

3. Save the file and restart the configured application server.

Play 2.4+ development mode

Follow the instructions for Activator/sbt to load the Java Library for Play 2.4+ (development mode).

Play 2.4+ production mode

The play start command does not support the -javaagent parameter. Instead, use a startup script to start the Play project.

1. Run the command activator dist to generate a startup script.

2. Open the startup script in the bin folder of the project directory.

3. Add the -javaagent parameter to the startup script:

   Workaround required: The Windows startup script needs a work around to overcome a known issue for Activator. This issue is related to a length limitation with cmd.exe command line strings.

   Use the short name path in the -javaagent parameter. For example, use C:\Progra~1 to reference the Program Files folder.

   bin\<startup script> -J-javaagent:"<library installation path>\solarwinds-apm-agent.jar"

Windows standalone Java application

To load the Java Library to a standalone Java application (for example, on a gRPC server or a Spring Boot embedded web server), add the -javaagent parameter when starting the java process. An example java process is:

java -javaagent:"<library installation path>\solarwinds-apm-agent.jar" -jar your-standalone-app.jar

Windows Activator/sbt

Activator and sbt are platforms to build and start Java or Scala apps. Apps on the Activator and sbt platforms are typically used for development, not production. Some frameworks, such as Play or spray, use sbt or Activator by default.

Activator

-javaagent:"<library installation path>\solarwinds-apm-agent.jar"

sbt

-javaagent:"<library installation path>\solarwinds-apm-agent.jar"

Azure App Service

1. From the Azure Portal, select the App Service.
2. Click Settings > Configuration.

3. For Tomcat, edit CATALINA_OPTS to include the -javaagent parameter. If CATALINA_OPTS does not exist, add a new option with the following argument.

   For other services, edit JAVA_OPTS to include the -javaagent parameter. If JAVA_OPTS does not exist, add the option with the following argument.

   -javaagent:/home/site/wwwroot/SolarWinds Observability/solarwinds-apm-agent.jar=service_key=<your service key>,log_file=solarwinds-apm-agent-runtime.log

4. Restart the App Service.

Diagnostics

A connectivity diagnostic tool is included with the Java Library installation. It should be run with the java command.

Diagnostic tool java command

For basic usage, use the following java command to run the tool. In the command:

• Replace path/to/solarwinds-apm-agent.jar with the path to the installed Java Library jar.

• Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

  The Service key is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

  The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

Java Library versions 2.0.0 and above:

java -cp "/path/to/solarwinds-apm-agent.jar" com.solarwinds.joboe.core.util.diagnostic.DiagnosticTools service_key=YourServiceKey

Java Library versions below 2.0.0:

java -cp "/path/to/solarwinds-apm-agent.jar" com.tracelytics.util.diagnostic.DiagnosticTools service_key=YourServiceKey

To include TLS debug messages with the diagnostic tool, use the following java command to run the tool. In the command:

• Replace path/to/solarwinds-apm-agent.jar with the path to the installed Java Library jar.

• Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

  The Service key is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

  The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

Java Library versions 2.0.0 and above:

java -Djava.security.debug=certpath,provider -Djavax.net.debug=ssl:session -cp "/path/to/solarwinds-apm-agent.jar" com.solarwinds.joboe.core.util.diagnostic.DiagnosticTools service_key=YourServiceKey

Java Library versions below 2.0.0:

java -Djava.security.debug=certpath,provider -Djavax.net.debug=ssl:session -cp "/path/to/solarwinds-apm-agent.jar" com.tracelytics.util.diagnostic.DiagnosticTools service_key=YourServiceKey

Parameters

The following parameters are available:

For example, run the following command to enable TLS debugging, set a timeout of 10 seconds, and save the diagnostic tool logs to a file named solarwinds-diagnostics.log:

java -Djava.security.debug=certpath,provider -Djavax.net.debug=ssl:session -cp "/path/to/solarwinds-apm-agent.jar" com.tracelytics.util.diagnostic.DiagnosticTools service_key=YourServiceKey timeout=10000 log_file=SolarWinds-diagnostics.log

If the diagnostic tool did not find any problems, the following message is shown:

INFO [SolarWinds APM] [OK] message: Diagnostics successful

The diagnostic tool exit codes are:

Log file locations

The Java Library 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 (catalina.out for Tomcat).

All logging messages from the Java Library are preceded by tags. For custom distro components, the tag [SolarWinds APM] is used. For OpenTelemetry components, the tag [otel.javaagent <date>] is used. By default, only messages with verbosity info or higher are reported. To see all debugging messages, set the logging level to debug or trace. See Logging level and Enable OpenTelemetry debug logging.

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.