SeaLights CD Agent for Java Application

Owned by Marc Amouyal
Last updated: Mar 21, 2024 by ronak.rahman
8 min read

 

Onboarding the Java CD Agent

These steps outline the onboarding steps needed on the environment, with the CD agent, added to each component that builds up the Application Under Test.

Each component within the application is a service running on a ‘dedicated’ JVM:

  • This could be an application server like Tomcat, JBoss, Websphere/Weblogic, or a standalone Java process using the Java Runtime Environment.

  • They can be on physical machines, VMs, containers, on-prem, or the cloud.

Configuration steps

  1. Download an Agent Token from the dashboard and make it available to each component configured with our agent.

    • This can be done by placing it in a file accessible to the agent or through an environment variable directly or through a secret manager.

  2. Download the CD agent and make it available to each component by copying it in, downloading it during startup, or mounting an external volume containing the agent.

  3. Create an “Integration Build Lab ID” entry of type “CD only” in the dashboard for the tested application (see picture on the right).

    • Do so in the settings of the SeaLights dashboard, under 'Cockpit & Onboarding → Integration Build Labs → CD Only'

    • The lab ID from this integration build entry needs to be provided to the CD agent through an environment variable.

  4. Add the CD agent to your JVM as a javaagent.

    • This is done by updating the JVM parameters of the component with -javaagent:sl-cd-agent.jar (See samples below)

  5. Set the relevant environment variables to be used by your component JVM, either each on its own before spinning up the JVM or through the JVM parameters themselves (using -Dsl. prefix) (See samples below)

 

 

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

  • Linux:  ps -ef | grep java

  • Windows: gwmi -Class Win32_Process -Filter "name like '%java%'" | Format-Table -Wrap -Property ProcessId, CommandLine (Powershell prompt)

Agent’s Parameters Reference

Mandatory parameters

Property

Required

Description

Property

Required

Description

sl.token
or
sl.tokenFile

Yes

The agent token to use for the secure connection, either as a parameter or in a file

The token can also be placed in a file called sltoken.txt alongside the agent and then this parameter is not required

sl.appName

Yes

Name of the component

sl.labId

Yes

The labId generated for the integration build entry in step #3

sl.buildName
or
sl.buildNameLocation

Yes

Name of the components version

sl.buildNameLocation value should be: FILE_TYPE;./file/location/props.txt;key
it consists of three parts separated by a colon (;) character:

  • FILE_TYPE - MANIFEST or PROPS

  • ./file/location/props.txt - the absolute or relative path of the file

  • key - The name of the key, under which the build name is located

If you have multiple different components under the same JVM, that get deployed independently. Which means the build name should include all of them, you can configure each one with a separate build name location flag with the following naming convention: sl.buildNameLocation_{appName}

The exact same value must be provided for the same version of the service being deployed multiple times
Recommendation: The buildname should allow you to trace back the service’s changes in your SCM. ex. the buildname comes from the Jenkin’s deployment job that shows the artifact version, which can be used to get SCM commit hash. This is useful when identifying changes identified in TGA report to those who made the changes for example.

sl.includes

Yes

Comma separated list of search pattern with wildcards ( * = any string, ? = any character) for the packages to be included in the scan. For example: 'com.example.*,io.*.demo,com.?ello.world'

Optional parameters

These parameters may be required due to your specific configuration or environment’s limitations (e.g., proxy).

Property

Required

Description

Property

Required

Description

sl.excludes

No

Comma separated list of search pattern with wildcards ( * = any string, ? = any character) for the packages to be excluded in the scan. For example: 'com.example.*,io.*.demo,com.?ello.world'

sl.branchName

No

Name of the branch of the component. If not provided, the lab branch name will be used

sl.workspace

No

Folders to search in for files to be scanned. Default is the current working directory

sl.filesincluded

No

Comma separated list of search pattern with wildcards for the files to be included in the scan. Default is *.class,*.jar,*.war,*.ear

sl.filesexcluded

No

Comma separated list of search pattern with wildcards for the files to be excluded from the scan

sl.recursive

No

Indication if to scan the workspace paths recursivly. Default is true

sl.proxy

No

Proxy for the agent to go through when communicating with SeaLights

sl.tags

No

Free text comma separated tags to help identify the agents later in the cockpit

Logging parameters

To enable logs, you can set the following parameters as environment variables or add them as -Dsl.* parameters. Both console output and file options are compatible and non-exclusive.

For logging into the console, add

-Dsl.log.toConsole=true -Dsl.log.level=info [--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED]

For logging into a file, add

-Dsl.log.toFile=true -Dsl.log.level=info -Dsl.log.folder=<path/with/permissions/> [--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED] [-Dsl.log.count=<value>] [-Dsl.log.limit=<arg>] [-Dsl.log.filename=<arg>]

Parameter

Required

Description

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)

--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED

No

Special JVM parameter to allow logging in Java 9 and later in addition to -Dsl.log.* options above. 
If the option is not provided, the test listener will work as usual, but logging will not work.

Sample Commands

Downloading the agent

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

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`

Configuration commands

JRE

BASH

Docker compose

A sample to use ${BUILD_NAME} dynamically is to set it in the .env file:

K8s using an init container

A sample to use ${BUILD_NAME} dynamically is to set it using envsubst

Docker file for java-cd-agent