Using Java Agents - Installing Test Listener as Java Agent

Owned by Jason Wides
Last updated: Dec 14, 2022
6 min read

In order to capture code coverage on your backend server, you need to install our test listener as a Java agent.
The listener needs to be placed alongside the server and added to the JVM command line using the -javaagent parameter together with its required parameters.


We recommend using the Lab ID method to link between the test listener and the test runner. For this you will have to pass the labid on top of the buildSessionId parameter.

  • If the artifact was packaged using the Include Resources option, then Test Listener will find the token and session ID inside it therefore you only need to pass the javaagent parameter:

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend [-Dsl.labId=<lab ID>]

  • If the artifact was not packaged using the Include Resources option, then the Test Listener needs to be provided the token and session ID as well:

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]

See 'Java Command Reference - Installing test listener as Java Agent' for full parameter details

We have gathered a list of the most common configurations below

When the application is up and running and the Sealights Listener agent configured, you can it is properly running from the Cockpit -> Agent Monitor screen.
You also have the ability to validate the JVM parameters in use with your application via the following command

  • Linux:  ps -ef | grep java

  • Windows: C:\\Windows\\System32\\wbem\\WMIC.exe process where "name like '%java%'" get commandline,processid (CMD prompt)

If the agent does not appear in the Cockpit Agent Monitor when your application is up and running, you can turn on the logging of the Sealights agent by adding one or both of the following parameters:

  • Console Output: -Dsl.log.level=info -Dsl.log.toConsole=true

  • File Output: -Dsl.log.level=info -Dsl.log.toFile=true -Dsl.log.folder=<path/to/folder/with/writing/permissions/>

More details about these parameters are detailed in a dedicated documentation section https://sealights.atlassian.net/wiki/spaces/SUP/pages/1933323/SeaLights+Java+agent+-+Command+Reference#Logging

Command Line

Usually the easiest is using the JAVA_TOOL_OPTIONS environment variable - Note it will affect every JVM that runs. If you need to affect specific JVM, then it can be provided directly to the JVM command line or to the JVM through its own technologies standards, like JAVA_OPTS, JAVA_OPTIONS etc.

  • If the artifact was packaged using the includeResources option, then Test Listener will find the token and session ID inside it therefore you only need to pass the javaagent parameter:

export JAVA_TOOL_OPTIONS="-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend [-Dsl.labId=<lab ID>]"

  • If the artifact was not packaged using the includeResources option, then the Test Listener needs to be provided the token and session ID as well:

Tomcat

The CATALINA_OPTS environment variable is used to pass configuration flags and system properties to the JVM that runs specifically the Tomcat server. Since Sealights Agent is usually in use only by Tomcat, you'll be best advised to use CATALINA_OPTS, whereas if you put your settings in JAVA_OPTS, it will be used locally by other Java applications as well. Both options are compatible with Sealights.

If you are running Tomcat from the command line, you can just set the environment variable, either from the command line or by updating the setenv.sh (or setenv.bat in windows)
If you are running Tomcat as a service on Linux, you will need to update the service file itself under /etc/init.d or any other startup script you have set up for the service.
Another option is to update the setenv.sh (setenv.bat on Windows) and update the JVM parameters inside it.

Tomcat as a Windows Service

If you are running your application ou need to edit the Windows service. There are three ways to do this:

  1. Start Tomcat9 with //MS//ServiceName to get an icon in the system tray which gives you a quick access to the configuration of the service.

  2. Open the service manager in the "Control Panel". There is an entry for Tomcat. In the editor, there is a tab where you can add additional JVM parameters (See screenshot below)

  3. Write a script which edits the config for you using a command like tomcat9 //US//... . This way, you can save the config somewhere for backup or update dynamically your server from a CI/CD script. You can refer to the official Tomcat documentation page for more details and options. For example, the ommand may look like tomcat9 //US//MyService --JvmOptions='-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=tomcat [-Dsl.labId=<lab ID>]'

 

JBoss & Wildfly

When the application server is JBoss or WildFly, you should also update the following parameters: jboss.modules.system.pkgs=org.jboss.byteman,io.sealights

Spring boot maven plugin

When using the spring boot maven plugin, you can set the jvmArguments property in the configuration section of the plugin to define the needed arguments.

Jetty

For the Jetty application server, if you are using the standard jetty.sh file then you can set the JAVA_OPTIONS environment variable with the javaagent, token and session ID.
Otherwise just add it to the JVM command you use to run jetty.

Gradle Build File

When using gradle to bring up a JVM with your application, you can set the javaagent in the jvmArgs

WebSphere

In the admin console:

  • Go to Servers→Application servers

  • Select your server

  • Go to Configuration→Service Infrastructure→Java and Process Management→Process Definition→Additional Properties→Java Virtual Machine

  • Add the agent configurations in the Generic JVM arguments 

WebLogic

In the admin console:

  • Go to Environments→Servers

  • Select your server

  • Go to Server Start

  • Add the agent configurations in the Arguments 

PCF/ VMWare Tanzu

Adding the Sealights java agent into you Pivotal Cloud Foundry / VMWare Tanzu Application Services is detailed in the following dedicated article:

Elastic Beanstalk

Beanstalk instance running a single Java process

  • In the AWS web console, select the requested EB application

  • Select the Configuration side menu

  • Modify the "Software" settings in the Configuration overview

  • Under Environment properties, add a new property:

    • JAVA_OPTS with the value -javaagent:sl-test-listener.jar -Dsl.tags=beanstalk [-Dsl.labId=<lab ID>]

  • Ensure the value is aligned to the location of the sl-test-listener.jar location within the Elastic Beanstalk instance

  • After the Beanstalk instance runs, ensure that the Test Listener is running from the Cockpit -> Agent Monitor screen.

Using Beanstalk configuration files .ebextensions (Tomcat)

  • Add .ebextensions folder to your application's directory

  • Inside .ebextensions, create a file called sealights-java.config

  • Now, we will need to specify to the configuration file that will be loaded into Elastic Beanstalk to perform the following actions:

    • Download the latest SeaLights agent

    • Unzip the downloaded agent

    • Give the required permissions

    • Pass the required -javaagent parameter to the JVM

    • Use the following sealights-java.config content as an example:

Beanstalk instance running multiple Java processes

In this case, a Procfile needs to be configured which defines the JVM configuration on a per-service basis:

  • Ensure the "Include Resources" checkbox is checked for this application, so that the buildSessionId.txt and the sltoken.txt files are packaged into the artifact

    • If unselected, the build session ID and token files need to be defined explicitly within the Java arguments

  • The Test Listener must be deployed onto the Elastic Beanstalk instance. This can be achieved by using the Maven Copy plugin, like described here.

Once the above prerequisites are met, a Procfile needs to be defined:

  • Within the Procfile, you specify the .jar with which SeaLights starts up using the following syntax:

For example: