SeaLights Java Agent - Using the Java Production Listener

The production listener samples real production data at specified intervals to add an additional layer of data that goes in line with the Test Gap Analytics report.

Downloading Agent file

Download it from: https://sl-repo.s3.amazonaws.com/sl-production-listener/sl-production-listener-3.1.1956.zip

Configuration File

Create a configuration file and provide its location using the -Dsl.config.file flag or call it 'sealights-pl-cfg.json' and place it in the current working directory of the JVM
It should contain the following minimum set of parameters:

• token or tokenFile - The token to be used to send the data to SeaLights (Mandatory for online mode)

• buildSessionId or buildSessionIdFile - The build session ID that was used to scan the application with (Mandatory for online mode)

• includes - Comma separated list of packages to include

• excludes - (Optional) Comma separated list of packages to exclude 

Below, a sample recommended configuration (Online mode) for the production listener agent.

{
	"token": "${SL_TOKEN}",
	"buildSessionIdFile": "/root/sealights/buildSessionId.txt",
	"includes":"com.example.*"
}

• See 'Configuration File Parameters Reference' for full parameter details

• The agent supports an “offline mode” described in the Advanced Settings section below.

Installing the Production Listener

The production listener needs to be placed alongside the server and added to the JVM command line using the -javaagent parameter together with its required parameters.

java -javaagent:/path/to/sl-production-listener.jar -Dsl.config.file=/path/to/config.json -jar yourapp.jar

On versions 8.5+ of Apache Tomcat, additional configuration may be required as described in the relevant section below.

Using the Production Insights Data

Data collected about application usage by the production listener will later be reported on the Test Gap Analytics report accessible from the dashboard.

Once production data is received for a reported application, the data will be reflected in the "usage" columns, referring to used code that is both modified and untested, as well as the overall used code which is untested.

Configuring Production Listener on Tomcat

On versions 8.5+ of Apache Tomcat, additional configuration needs to be made in the Tomcat configuration

Errors related to StandardJarScanner 

This element represents the component that is used to scan the web application for JAR files and directories of class files.

It is normally used to identify configuration files crucial to the webapp's initialization.

Disabling the JarScanner

1. In your Tomcat directory, open the context.xml file

2. Edit the following into the file's contents:

   <context>
     ...
     <JarScanner scanManifest="false"/>
   </context>

   XML

Advanced Settings

Offline Mode

Saving Coverage File locally

{
	"offlineMode": "true",
	"token": "${SL_TOKEN}",
	"buildSessionId": "${SL_BUILD_SESSION_ID}",
	"includes":"com.example.*"
}

See 'Configuration File Parameters Reference' for full parameter details.

Uploading Production Listener results to SeaLights

The production listener can be invoked manually in order to send the .csv file containing the production data directly to SeaLights, you’ll need to use the upload command (-u) and pass the coverage file location via the -f flag:

java -javaagent:/path/to/sl-production-listener.jar -u -f csvFile.csv

To upload the file, the following parameters need to be defined in the configuration JSON:

• Token/TokenFile

• buildSessionId/appName

• includes

Using Command Line Parameters instead of Configuration file

If necessary, the Production Listener will accept some configuration parameters as JVM parameters rather than passed via a JSON configuration file, although the later option is the recommended one.

java -javaagent:/path/to/sl-production-listener.jar -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=/path/to/buildSessionId.txt -Dsl.includes=com.example.* -jar yourapp.jar

Logging

In order to enable logs you can set the following prpoerties as well using the -D java flag

Configuration File Parameters Reference

Create a configuration file and provide its location using the -Dsl.config.file flag or call it 'sealights-pl-cfg.json' and place it in the current working directory of the JVM
It should contain the following minimum set of parameters:

• token or tokenFile - The token to be used to send the data to SeaLights (Mandatory for online mode)

• appName or buildSessionId or buildSessionIdFile 

  • buildSessionId or buildSessionIdFile - The build session ID that was used to scan the application with (Mandatory for online mode)

  • appName - The application name used to identify the reporting application in SeaLights - this field is interchangeable with the buildSessionId

• includes - Comma separated list of packages to include

• excludes - Comma separated list of packages to exclude 

• offlineMode - If true, the data is saved locally, if false (default) the data is sent directly to SeaLights

• activeIntervalMins - The interval in minutes to be active (Default is 2)

• idleIntervalMins - The interval in minutes to be idle (Default is 58)

• saveFtpsIntervalSecs - The interval in seconds to update the report file with the footprint data (Default is 20)

• enableMethodsCoverage - Set to true to capture coverage for methods. Set to false to only capture coverage for an entire class

• classLoadersExcluded - Comma separated list of class loaders to exclude 

• jarExcluded - Comma separated list of jar files to exclude 

• failuresThreshold - In offline mode, if the agent fails to save the report file, this specifies the number of times to retry before stopping to work (Default 2)

• fileStorage - In offline mode, the folder location to save the report files in (Default 'csvFiles')

Below, you’ll find few sample files of different possible configurations to use with the production listener agent.

{
	"offlineMode": "true",
	"tokenFile": "sltoken.txt",
	"appName": "testApplication",
	"includes":"com.example.*"
}

{
	"tokenFile": "sltoken.txt",
	"buildSessionId": "${SL_BUILD_SESSION_ID}",
	"includes":"com.example.*",
	"offlineMode": "false",
	"activeIntervalMins": 2,
	"idleIntervalMins": 58,
	"saveFtpsIntervalSecs": 20,
	"enableMethodsCoverage":true,
	"failuresThreshold":2
}

{
	"offlineMode": "true",
	"tokenFile": "sltoken.txt",	
	"buildSessionId": "${SL_BUILD_SESSION_ID}",
	"includes":"com.example.*",
	"activeIntervalMins": 2,
	"idleIntervalMins": 58,
	"saveFtpsIntervalSecs": 20,
	"enableMethodsCoverage":true,
	"failuresThreshold":2,
	"fileStorage":"csvFiles"
}