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)

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 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'` You should prepend each of the enlisted packages with asterisk sign (e.g. `-Dsl.includes=com.example.*`) when you are running the application with the servlet container (e.g. Tomcat),

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 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` 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 with wildcards for the files to be excluded from the scan 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 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
`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

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

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

  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:

BUILD_NAME=weaveworksdemos/queue-master:0.3.1

K8s using an init container

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

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

Docker file for java-cd-agent

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

SeaLights CD Agent for Java Application