Step 3: Collecting Code Coverage

In this section, we'll cover how to install Sealights for a single service. This setup should be repeated for each microservice that your have

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

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

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 NameDescriptionRemarks

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

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:

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:

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

ps -ef | grep java

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.

For logging into the console, add:

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

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.

Last updated

All rights reserved to Sealights Technologies ltd.