Java - Agent Installation and Setup

The current installation guide assumes you completed the steps mentioned on the Simple Deployment page.

Prerequisites

Download the Sealights Agent

Download the Sealights agent to the machine with the application under test. If there are multiple machines, make the agent available on every machine (or container) in the environment.

The agent is downloadable from the following URL: https://agents.sealights.co/sl-cd-agent/sl-cd-agent-latest.zip

You can use the following commands to automate the process in the environment setup script

Linux

wget -nv https://agents.sealights.co/sl-cd-agent/sl-cd-agent-latest.zip 
unzip -oq sl-cd-agent-latest.zip 
echo "Sealights CD Agent version used is: $(cat version.txt)"

Powershell

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
iwr https://agents.sealights.co/sl-cd-agent/sl-cd-agent-latest.zip -OutFile sl-cd-agent-latest.zip -ErrorAction Continue
if (Test-Path -Path sl-cd-agent-latest.zip -PathType Leaf) {
  Expand-Archive .\sl-cd-agent-latest.zip 
}

Download the Agent Token

Download the Agent Token you have generated in the settings page, as a file (called by default sltokent.txt), and place it in the folder where you placed the agent.

Setup

In order to configure the agent, please add the Sealights agent to your Java virtual machine (JVM) as a -javaagent.

The Sealights Agent relies on specific parameters that can be specified by setting Java system variables, which are simple key-value pairs, using the -D argument on the startup command. Our agent will programmatically retrieve relevant parameters to it when they are specified with the specific -Dsl. prefix.

This is done by updating the JVM parameters of the application component with the following:

-javaagent:sl-cd-agent.jar -Dsl.tokenFile=sltoken.txt \
    -Dsl.appName=<your-service-name> -Dsl.buildName=<your-service-version> \
    -Dsl.includes=<your-service-package> -Dsl.workspace=<path-to-service-artifact> \
    -Dsl.labId=<labid-defined-previously-in-settings> 

For example, your configuration may look like this:

-javaagent:/sealights/sl-cd-agent.jar -Dsl.tokenFile=/sealights/sltoken.txt \
    -Dsl.appName=backend-service -Dsl.buildName=1.0.26 \
    -Dsl.includes="*com.mycompany.*" -Dsl.workspace=/app/ \
    -Dsl.labId=integ_qa1_retail

The required parameters are detailed as follows:

Parameter Name	Description	Remarks
sl.tokenFile	The agent token in a file to use for the secure connection	See the token management section for more details. If you're managing your credentials via some manager, you can pass the token as an environment variable (for example $SL_TOKEN) and therefore you'll need to update the parameter to be sl.token (without the term File) , e.g. sl.token=$SL_TOKEN
sl.appName	Name of the application component.	We recommend limiting the application name to a maximum of 50 characters and utilizing alphanumeric characters (A-Z and numbers).
sl.labId	The labId generated in the dashboard settings	This labId must be the same used by all the agents deployed in the same environment.
sl.buildName	The component version. If the application component is being installed on multiple machines in the same environment, the exact same value has to be used.	When the artifact is updated/modified, this version number must change accordingly. We recommend limiting the application name to a maximum of 30 characters and utilizing alphanumeric characters (A-Z and numbers).
sl.includes	Comma separated list of search pattern with wildcards for the packages to be included in the scan	For example: - com.mycompany.* - io.demo.*, com.foo.*
sl.workspace	Comma-separated list of folders to search in for files to be scanned.	Default is the folder the artifact is located in and the classpath

Optional Agent Parameters

Use the following additional parameters to fine-tune your setup:

• sl.excludes - Comma-separated list of search patterns with wildcards for the packages to be excluded in the scan

• sl.branchName - Name of the branch of the component. If not provided, the lab branch name will be used

• sl.workspace - Comma-separated list of folders to search in for files to be scanned. Default is the folder the artifact is located in and the classpath

• sl.recursive - Indication if to scan the workspace paths recursively. Default is true

• sl.proxy - Proxy for the agent to go through when communicating with SeaLights

• sl.tags - Free text comma-separated tags to help identify the agents later in the cockpit.

Common Integrations

We have gathered a list of the most common configurations below:

Docker

JBoss/Wildfly

Kubernetes

Tomcat

CLI

Validation

When the application is up and running and the Sealights Agent configured, you can see it is properly running from the Cockpit -> Live Agents Monitor screen.

See example for properly running agents. Verify that the app, branch, build. labID and machine name match the agent you ran:

Live Agents Monitor

If no agents appears please follow the troubleshooting instructions below.

Troubleshooting

Service is running:

You have the ability to validate the JVM parameters in use with your application via your terminal

Linux

ps -ef | grep java

Powershell

gwmi -Class Win32_Process -Filter "name like '%java%'" | Format-Table -Wrap -Property ProcessId, CommandLine

Enabling agent logs:

You can enable logging using additional parameters as environment variables or add them as -Dsl.* parameters. Both console output and file options are compatible and non-exclusive.

Console

For logging into the console, add:

-Dsl.log.toConsole=true -Dsl.log.level=info

File

For logging into a file, add:

-Dsl.log.toFile=true -Dsl.log.level=info -Dsl.log.folder=<path/with/permissions/> 

The user running the Java process must have writing permissions to the folder specified as the log.folder parameter. Lack of permission may lead to an empty folder.

The default file name is java-agent.log.

Logging Parameters

Parameter	Required	Description
sl.log.level	No	Sets the log level to one of the following: "off", "error", "warn", "info", "debug"
sl.log.toConsole	No	Set to true to enable log output to the console
sl.log.toFile	No	Set to true to enable log output to a file
sl.log.folder	No	Provide a folder to save the log files in
sl.log.filename	No	Provide the name of the log file
sl.log.count	No	Limit the number of log files to create. Default: 10
sl.log.limit	No	Limit the size of the log file in megabytes (MB). Default value is 10 (i.e. 10*1024 KB)

Java classes found by the agent

After enabling logs, search in the logs for the pattern

Verity agent was able to find your Java classes by writing to the log line similar to the below:

// Some code2023-06-11 06:23:36,859 INFO  [|Thread-4    |] i.s.o.a.f.s.i.MetricsCollector : scan report - jars: 3, classes: 18, methods: 42, total time: 698

if number of jars is 0 or less from the amount of jars in your application check sl.workspace parameter and verify it's correct and the jars are in that folder

if number of classes is 0 or low check the sl.includes parameter and verify it's in your application packages structure.

If further assistance is required, please contact Sealights Support.

Next Step

You're now ready to perform a quick Manual Test to ensure the Sealights agent can capture coverage properly.

After the coverage is captured from Manual Tests, you're set to integrate with your Test Automation framework.