Table of Contents

minLevel	1
maxLevel	2

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

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.
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.
- The agent is downloadable from the following URL: https://agents.sealights.co/sl-cd-agent/sl-cd-agent-latest.zip
- You can refer to the following sample commands below: https://sealights.atlassian.net/wiki/spaces/SUP/pages/3163848778/SeaLights+CD+Agent#Downloading-the-agent
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.
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)
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)

Tip

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

sl.token
or
sl.tokenFile

Yes

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

Info
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

NoteThe exact same value must be provided for the same version of the service being deployed multiple times

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, they get deployed independently. This 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}

Note

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

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

Note
You should prepend each of the enlisted packages with an asterisk sign (e.g., `-Dsl.includes=com.example.`) when you are running the application with the servlet container (e.g., Tomcat), or when the deployed configuration contains classes exploded from the java archive.

Optional parameters

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

Property	Required	Description
sl.excludes	No	Comma-separated list of search

pattern

patterns 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

patterns with wildcards for the files to be included in the scan. Default is *.class,*.jar,*.war,*.ear

Note
Each file is handled with its full path, therefore an asterisk must be provided at the beginning unless specifying the full path in the value

sl.filesexcluded

No

Comma-separated list of search

pattern

patterns with wildcards for the files to be excluded from the scan

Note
Each file is handled with its full path, therefore an asterisk must be provided at the beginning unless specifying the full path in the value

sl.recursive

No

Indication

if to scan

for scanning the workspace paths

recursivly

recursively.

Default

The default value 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

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

For logging into a file, add

Code Block

-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
`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

The 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

Code Block

language	bash

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

Table of Contents

minLevel	3
maxLevel	7
exclude	parameters

JRE

Code Block

language	bash

java -javaagent:/sealights/sl-cd-agent.jar -Dsl.token=${SL_TOKEN} -Dsl.appName=microservices_orders -Dsl.buildName=weaveworksdemos/carts:0.4.8 -Dsl.tags=JRE -Dsl.labId=integ_test_microservices -Dsl.includes="works*" -jar app.jar

BASH

Code Block

language	bash

export JAVA_TOOL_OPTIONS="-javaagent:/sealights/sl-cd-agent.jar -Dsl.tokenFile=/sealights/sltoken.txt -Dsl.appName=microservices_orders -Dsl.buildName=weaveworksdemos/carts:0.4.8 -Dsl.tags=bash -Dsl.labId=integ_test_microservices -Dsl.includes=works*"

java -jar app.jar

Docker compose

Code Block

language	yaml

  queue-master:
    image: weaveworksdemos/queue-master:0.3.1
    hostname: queue-master
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: always
    cap_drop:
      - all
    cap_add:
      - NET_BIND_SERVICE
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid
    environment:
      - JAVA_OPTS=-javaagent:/sealights/sl-cd-agent.jar -Dsl.tokenFile=/sealights/sltoken.txt -Dsl.appName=microservices_queuemaster -Dsl.buildName=${BUILD_NAME} -Dsl.tags=script,container -Dsl.labId=integ_test_microservices -Dsl.includes=works*
    volumes:
      - /tmp/sealights:/sealights

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

Code Block
BUILD_NAME=weaveworksdemos/queue-master:0.3.1

K8s using an init container

Code Block

language	yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: carts
  labels:
    name: carts
  namespace: sock-shop
spec:
  replicas: 1
  selector:
    matchLabels:
      name: carts
  template:
    metadata:
      labels:
        name: carts
    spec:
      initContainers:
      - name: java-cd-agent
        image: java-cd-agent:latest
        imagePullPolicy: Never
        command: ["/bin/sh", "-c", "cp /download/sl-cd-agent.jar /sealights"]
        volumeMounts:
          - mountPath: /sealights
            name: java-cd-agent-file
      containers:
      - name: carts
        image: weaveworksdemos/carts:0.4.8
        env:
        - name: sl.token
          valueFrom:
            secretKeyRef:
              name: sealights
              key: SL_TOKEN
        - name: sl.appName
          value: microservices_carts
        - name: sl.buildName
          value: ${BUILD_NAME}
        - name: sl.tags
          value: k8s,ic
        - name: sl.labId
          value: integ_test_microservices
        - name: sl.includes
          value: works*
        - name: JAVA_TOOL_OPTIONS
          value: -javaagent:/sealights/sl-cd-agent.jar
        - name: JAVA_OPTS
          value: -Xms64m -Xmx128m -XX:+UseG1GC -Djava.security.egd=file:/dev/urandom -Dspring.zipkin.enabled=false
        resources:
          limits:
            cpu: 300m
            memory: 500Mi
          requests:
            cpu: 100m
            memory: 200Mi
        ports:
        - containerPort: 80
        securityContext:
          runAsNonRoot: true
          runAsUser: 10001
          capabilities:
            drop:
              - all
            add:
              - NET_BIND_SERVICE
          readOnlyRootFilesystem: true
        volumeMounts:
        - mountPath: /tmp
          name: tmp-volume
        - mountPath: /sealights
          name: java-cd-agent-file
      volumes:
      - name: tmp-volume
        emptyDir:
          medium: Memory
      - name: java-cd-agent-file
        emptyDir: {}
      nodeSelector:
        beta.kubernetes.io/os: linux

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

Code Block

language	bash

export BUILD_NAME=weaveworksdemos/carts:0.4.8
envsubst < k8s.yaml | kubectl apply -f -

Docker file for java-cd-agent

Code Block
FROM alpine:3.17.0 ADD sl-cd-agent.jar /download/sl-cd-agent.jar

Versions Compared

Old Version 1

New Version Current

Key

Onboarding the Java CD Agent

Configuration steps

Agent’s Parameters Reference

Mandatory parameters

Optional parameters

Logging parameters

Sample Commands

Downloading the agent

Configuration commands

JRE

BASH

Docker compose

K8s using an init container

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Onboarding the Java CD Agent

Configuration steps

Agent’s Parameters Reference

Mandatory parameters

Optional parameters

Logging parameters

Sample Commands

Downloading the agent

Configuration commands

JRE

BASH

Docker compose

K8s using an init container