Documentation forSolarWinds Observability

Install and load the 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 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. The environment variable can also be defined 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 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.

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

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 Observability

  3. Download the library JAR and json config files to the library's folder
  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.

    • 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, see 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 Observability.
  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 detailing how to add the parameter for your specific application server, see Load the library (Linux web servers) and Load the library (Windows web servers).

Replace <library installation path> with the path for the Java Library installation, defined during Install the library JAR.

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)

  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 above -javaagent parameter 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)

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

  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.

JBoss 7.x (domain mode)

  1. Open the JBoss domain config file. For JBoss 7.1.1 installations, it is often located at /usr/local/jboss-7.1.1/domain/configuration/domain.xml.

  2. Modify an existing or add a new jvm-options node with value attribute defined with 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 JBoss in domain mode.

JBoss 7.x (standalone mode)

  1. Find the directory containing your JBoss installation. For JBoss 7.1.0 installations, it is often located at /usr/local/jboss-as-7.1.0.Final.

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

  3. Append the JAVA_OPTS environment variable setting with the -javaagent parameter:

    JAVA_OPTS="$JAVA_OPTS -javaagent:<library installation path>/solarwinds-apm-agent.jar"
  4. Save the file and restart JBoss in standalone mode.

WebLogic (using the administration console for managed servers)

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)

  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)

  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.

WebSphere (using the administrative console)

See Java virtual machine settings in IBM WebSphere Application Server documentation for how to use the set these values with the WebSphere administrative console.

  1. Start the WebSphere Application Server administrative console.
  2. Under Servers > Server Types > WebSphere application servers, click the application server that has the Java Library installed.
  3. In the Server Infrastructure section, click Java and process management > Process definition > Java virtual machine
  4. In the Configuration tab, locate the Generic JVM arguments field, and add the -javaagent parameter. Replace any spaces in the path with ~.

    -javaagent:<library installation path>/solarwinds-apm-agent.jar
  5. Apply and save the changes.
  6. Restart the configured application server.

WebSphere (using server.xml)

  1. Locate the server config file of the WebSphere Application Server that has the Java Library installed. It typically is located at ${PROFILE_HOME}\config\cells\${CELL}\nodes\${NODE}\servers\${SERVER}\server.xml.
  2. Locate the Server/processDefinitions/jvmEntries XML node. Add the -javaagent parameter to the attribute genericJvmArguments. Replace any spaces in the path with ~.

    -javaagent:<library installation path>/solarwinds-apm-agent.jar
  3. Save the file and restart the configured application server.

WebSphere Liberty Profile

  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

To load the Java Library to a specific sbt project, add the following line to .sbtopts in your sbt project folder. If the .sbtopts file does not exist, create a new file with the following line added.

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

Activator

The following line should be used to load the Java Library for Activator projects:

-javaagent:<library installation path>/solarwinds-apm-agent.jar
  • To load the Java Library for all Activator projects when running in development mode (for example, using the command activator run) add the -javaagent line to activatorconfig.txt located in the user\home\directory\.activator\ folder.

  • To load the Java Library for a specific version only, add the -javaagent line to the end of activatorconfig.txt located in the user\home\directory\.activator\version\ folder.

  • To load the Java Library for a specific Activator project, add the -javaagent line to environment variables ACTIVATOR_OPTS, SBT_OPTS or JAVA_OPTS.

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

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

    -javaagent:/home/site/wwwroot/SolarWinds Observability/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

The JVM option can also be set using the Tomcat monitor application. See the Tomcat 9 Windows How-To in Apache Tomcat documentation for more details about setting JVM options.

  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)

  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)

  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.

JBoss 7.x (domain mode)

  1. Find the directory containing your JBoss installation.

  2. Open the JBoss domain.xml domain configuration file in the \domain\configuration\ folder of your JBoss 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 JBoss 7.x (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 JBoss in domain mode.

JBoss 7.x (standalone mode)

  1. Find the directory containing your JBoss installation and open the \bin\ folder.

  2. Open the standalone.conf.bat file that defines the JAVA_OPTS variable.

  3. Locate the last line of set "JAVA_OPTS ... ", and add a new line that contains the -javaagent parameter.

    set "JAVA_OPTS=%JAVA_OPTS% -javaagent:"<library installation path>\solarwinds-apm-agent.jar""
  4. Save the file and restart JBoss in standalone mode.

WebLogic (admin console for managed servers)

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)

  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)

  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.

WebSphere (using the administrative console)

See Java virtual machine settings in IBM WebSphere Application Server documentation for how to use the set these values with the WebSphere administrative console.

  1. Start the WebSphere Application Server administrative console.

  2. Under Servers > Server Types > WebSphere application servers, click the application server that has the Java Library installed.

  3. In the Server Infrastructure section, click Java and process management > Process definition > Java virtual machine

  4. In the Configuration tab, locate the Generic JVM arguments field, and add the following argument. Replace any spaces in the path with ~.

    -javaagent:<library installation path>\solarwinds-apm-agent.jar
  5. Apply and save the changes.
  6. Restart the configured application server.

WebSphere (using server.xml)

  1. Locate the server config file of the WebSphere Application Server that has the Java Library installed. It typically is located at ${PROFILE_HOME}\config\cells\${CELL}\nodes\${NODE}\servers\${SERVER}\server.xml.

  2. Locate the Server/processDefinitions/jvmEntries XML node. Add the following to the attribute genericJvmArguments. Replace any spaces in the path with ~.

    -javaagent:<library installation path>\solarwinds-apm-agent.jar
  3. Save the file and restart the configured application server.

WebSphere Liberty Profile

  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

The following line should be used to load the Java Library for Activator projects:

-javaagent:"<library installation path>\solarwinds-apm-agent.jar"
  • To load the Java Library for all Activator projects when running in development mode (for example, using the command activator run) add the -javaagent line to activatorconfig.txt located in the user\home\directory\.activator\ folder.

  • To load the Java Library for a specific version only, add the -javaagent line to the end of activatorconfig.txt located in the user\home\directory\.activator\version\ folder.

  • To load the Java Library for a specific Activator project, add the -javaagent line to environment variables CFG_OPTS, ACTIVATOR_OPTS, SBT_OPTS or JAVA_OPTS.

sbt

To load the Java Library to a specific sbt project, add the following line to the environment variable SBT_OPTS or JAVA_OPTS.

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

    For other services, edit JAVA_OPTS to include the -javaagent parameter. If JAVA_OPTS does not exist, add the option with the below 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.

The Java Library writes logs to the stdout and stderr streams by default. For Windows application servers that do not redirect those streams to any file (for example Tomcat), the logs might be lost. The -javaagent parameter provided above redirects logs to the file solarwinds-apm-agent-runtime.log. See Detailed logging configuration.

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.

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.

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:

service_key (required) The Service key to use with the diagnostic tool.
collector (optional) The collector endpoint to verify a connection to. If not specified, the default endpoint apm.collector.cloud.solarwinds.com:443 is used. See Endpoint URIs for the correct URI to use for the SolarWinds APM collector.
timeout (optional) The max time to wait (in milliseconds) for the diagnostic tool to finish. The default wait is 5 seconds.
log_file

(optional) The file location where the diagnostic tool's logs should be sent. The location can be a path relative to the current directory or an absolute path. By default, the log output is the console.

The user running the diagnostic tool must have permission to write to the file. If the user does not have write permissions, the message WARNING [SolarWinds APM] Cannot write to log file will be printed.

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

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:

Exit Status Code Name Description
0 OK Diagnostics were successful
101 UNKNOWN_ERROR An unexpected error occurred. See the error message for details.
102 INVALID_FORMAT_ARGUMENT An argument passed to the diagnostic tool was not in a valid format. For example, the Service key format is invalid. See the error message for details.
103 INVALID_ARGUMENTS An argument passed to the diagnostic tool was incorrect. For example, an argument name used is not recognized. See the error message for details.
104 INVALID_SERVICE_KEY The Service key was rejected by the SolarWinds APM collector.
105 CONNECTION_FAILURE Failed to connect to the SolarWinds APM collector within the timeout limit (default is 5 seconds). Most connection problems get this status code.
106 TRY_LATER The SolarWinds APM collector rejected the diagnostic request with status TRY_LATER.
107 LIMIT_EXCEEDED The SolarWinds APM collector rejected the diagnostic request with status LIMIT_EXCEEDED.
108 CONNECTION_FAILURE_FATAL There was a fatal failure connecting to the SolarWinds APM collector. For example, the TLS cert specified by SW_APM_TRUSTEDPATH was not found. See the error message for details.

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.