Using Java Agents - Installing the Coverage Listener as a JVM Java Agent
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:
Get-CimInstance Win32_Process | Where-Object { $_.Name -like '*java*' } | Select-Object CommandLine, ProcessId
(Powershell)CMD Promt:
C:\\Windows\\System32\\wbem\\WMIC.exe process where "name like '%java%'" get commandline,processid
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 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:
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.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)
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 liketomcat9 //US//MyService --JvmOptions='-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=tomcat [-Dsl.labId=<lab ID>]'
Kubernetes using an Init container
In the sample YAML file below, we dynamically download the agent into a sidecar container to make it available to the JVM of our application container. We’re using a lightweight base image that contains wget
and unzip
.
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
.ebextension
s folder to your application's directoryInside
.ebextensions
, create a file calledsealights-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 JVMUse 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: