Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 50 Next »

In order to capture code coverage on your backend server, you need to install our test listener as a Java agent.
The listener needs to be placed alongside the server and added to the JVM command line using the -javaagent parameter together with its required parameters.


We recommend using the Lab ID method to link between the test listener and the test runner. For this you will have to pass the labid on top of the buildSessionId parameter.

  • If the artifact was packaged using the Include Resources option, then Test Listener will find the token and session ID inside it therefore you only need to pass the javaagent parameter:

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend [-Dsl.labId=<lab ID>]
  • If the artifact was not packaged using the Include Resources option, then the Test Listener needs to be provided the token and session ID as well:

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]

We have gathered a list of the most common configurations below

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

  • Linux:  ps -ef | grep java

  • Windows: C:\\Windows\\System32\\wbem\\WMIC.exe process where "name like '%java%'" get commandline,processid (CMD prompt)

If the agent does not appear in the Cockpit Agent Monitor when your application is up and running, you can turn on the logging of the Sealights agent by adding one or both of the following parameters:

  • Console Output: -Dsl.log.level=info -Dsl.log.toConsole=true

  • File Output: -Dsl.log.level=info -Dsl.log.toFile=true -Dsl.log.folder=<path/to/folder/with/writing/permissions/>

More details about these parameters are detailed in a dedicated documentation section https://sealights.atlassian.net/wiki/spaces/SUP/pages/1933323/SeaLights+Java+agent+-+Command+Reference#Logging

You can validate the inclusion of buildSessionId.txt and sltoken.txt files inside the artifact using a command like: jar tf *.jar | grep txt or jar tf *.jar | grep 'buildSessionId.txt\|sltoken.txt'

Command Line

Usually the easiest is using the JAVA_TOOL_OPTIONS environment variable - Note it will affect every JVM that runs. If you need to affect specific JVM, then it can be provided directly to the JVM command line or to the JVM through its own technologies standards, like JAVA_OPTS, JAVA_OPTIONS etc.

  • If the artifact was packaged using the includeResources option, then Test Listener will find the token and session ID inside it therefore you only need to pass the javaagent parameter:

export JAVA_TOOL_OPTIONS="-javaagent:/path/to/sl-test-listener.jar  -Dsl.tags=backend [-Dsl.labId=<lab ID>]"
  • If the artifact was not packaged using the includeResources option, then the Test Listener needs to be provided the token and session ID as well:

export JAVA_TOOL_OPTIONS="-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]"

Setting the JAVA_TOOL_OPTIONS will affect every JVM that runs on the machine. If you want to only have our agent run with a specific JVM, then you shouldn't use this option and prefer a more specific environment variable.

JAVA_TOOL_OPTIONS is limited to 1024 characters and adding parameters above this buffer size will cause java to ignore it completely

Tomcat

The CATALINA_OPTS environment variable is used to pass configuration flags and system properties to the JVM that runs specifically the Tomcat server. Since Sealights Agent is usually in use only by Tomcat, you'll be best advised to use CATALINA_OPTS, whereas if you put your settings in JAVA_OPTS, it will be used locally by other Java applications as well. Both options are compatible with Sealights.

CATALINA_OPTS+="-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=tomcat [-Dsl.labId=<lab ID>]"

If you are running Tomcat from the command line, you can just set the environment variable, either from the command line or by updating the setenv.sh (or setenv.bat in windows)
If you are running Tomcat as a service on Linux, you will need to update the service file itself under /etc/init.d or any other startup script you have set up for the service.
Another option is to update the setenv.sh (setenv.bat on Windows) and update the JVM parameters inside it.

Tomcat recommends using a setenv script to specify environment variables. You can learn more about the setenv script, including how to find or create it as needed, by consulting RUNNING.txt, which is included with every distribution of Tomcat.

Tomcat as a Windows Service

If you are running your application ou need to edit the Windows service. There are three ways to do this:

  1. Start Tomcat9 with //MS//ServiceName to get an icon in the system tray which gives you a quick access to the configuration of the service.

  2. Open the service manager in the "Control Panel". There is an entry for Tomcat. In the editor, there is a tab where you can add additional JVM parameters (See screenshot below)

  3. Write a script which edits the config for you using a command like tomcat9 //US//... . This way, you can save the config somewhere for backup or update dynamically your server from a CI/CD script. You can refer to the official Tomcat documentation page for more details and options. For example, the ommand may look like tomcat9 //US//MyService --JvmOptions='-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=tomcat [-Dsl.labId=<lab ID>]'

Kubernetes using an Init container

In the sample Yaml file below, we dynamically download the agent into a side car container to make it available to the JVM of our application container

spec:
  initContainers:
  - name: java-cd-agent
    image: busybox:latest
    imagePullPolicy: IfNotPresent
    command: ["/bin/sh", "-c"]
    args:
      - |
        wget -nv -O /tmp/sealights-java-agents.zip https://agents.sealights.co/sealights-java/sealights-java-latest.zip;
        mkdir -p /sealights;
        unzip -j /tmp/sealights-java-agents.zip sl-test-listener.jar -d /sealights;
    volumeMounts:
      - mountPath: /sealights
        name: sealights-java-coverage-listener
  containers:
  - name: your-main-container
    # other container configurations
    env:
    - name: sl.tags
      value: k8s
    - name: sl.labId
      value: integ_test_microservices
    - name: JAVA_TOOL_OPTIONS
      value: -javaagent:/sealights/sl-test-listener.jar 
    volumeMounts:
    - mountPath: /sealights
      name: sealights-java-coverage-listener
  volumes:
    - name: sealights-java-coverage-listener
      emptyDir: {}

JBoss & Wildfly

When the application server is JBoss or WildFly, you should also update the following parameters: jboss.modules.system.pkgs=org.jboss.byteman,io.sealights

JAVA_OPTS+="-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=jboss -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>] -Djboss.modules.system.pkgs=org.jboss.byteman,io.sealights"

Spring boot maven plugin

When using the spring boot maven plugin, you can set the jvmArguments property in the configuration section of the plugin to define the needed arguments.

<plugin>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-maven-plugin</artifactId>
	<configuration>
		<jvmArguments>-javaagent:${sl.testListenerPath} -Dsl.tags=springboot -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]</jvmArguments>
	</configuration>
</plugin>

Note that if you are using the maven plugin you can use the ${sl.testListenerPath} instead of downloading and defining the actual test listener jar file.

Jetty

For the Jetty application server, if you are using the standard jetty.sh file then you can set the JAVA_OPTIONS environment variable with the javaagent, token and session ID.
Otherwise just add it to the JVM command you use to run jetty.

export JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/path/to/sl-test-listener.jar -Dsl.tags=jetty -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]"

Supported Jetty versions are: 9.1.1 and on

Gradle Build File

When using gradle to bring up a JVM with your application, you can set the javaagent in the jvmArgs

jvmArgs=["-javaagent:/path/to/sl-test-listener.jar", "-Dsl.tags=gradlebackend", "-Dsl.tokenFile=/path/to/sltoken.txt", "-Dsl.buildSessionId=buildSessionId.txt" ["-Dsl.labId=<lab ID>"] ]

WebSphere

In the admin console:

  • Go to Servers→Application servers

  • Select your server

  • Go to Configuration→Service Infrastructure→Java and Process Management→Process Definition→Additional Properties→Java Virtual Machine

  • Add the agent configurations in the Generic JVM arguments 

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=websphere -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]

WebLogic

In the admin console:

  • Go to Environments→Servers

  • Select your server

  • Go to Server Start

  • Add the agent configurations in the Arguments 

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=weblogic -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]

PCF/ VMWare Tanzu

Adding the Sealights java agent into you Pivotal Cloud Foundry / VMWare Tanzu Application Services is detailed in the following dedicated article:

Elastic Beanstalk

Beanstalk instance running a single Java process

  • In the AWS web console, select the requested EB application

  • Select the Configuration side menu

  • Modify the "Software" settings in the Configuration overview

  • Under Environment properties, add a new property:

    • JAVA_OPTS with the value -javaagent:sl-test-listener.jar -Dsl.tags=beanstalk [-Dsl.labId=<lab ID>]

  • Ensure the value is aligned to the location of the sl-test-listener.jar location within the Elastic Beanstalk instance

The Test Listener must be deployed onto the Elastic Beanstalk instance. This can be achieved by using the Maven Copy plugin, like described here

  • After the Beanstalk instance runs, ensure that the Test Listener is running from the Cockpit -> Agent Monitor screen.

Using Beanstalk configuration files .ebextensions (Tomcat)

  • Add .ebextensions folder to your application's directory

  • Inside .ebextensions, create a file called sealights-java.config

  • Now, we will need to specify to the configuration file that will be loaded into Elastic Beanstalk to perform the following actions:

    • Download the latest SeaLights agent

    • Unzip the downloaded agent

    • Give the required permissions

    • Pass the required -javaagent parameter to the JVM

    • Use the following sealights-java.config content as an example:

      commands: 1-download-java-agent: command: "sudo curl --location https://agents.sealights.co/sealights-java/sealights-java-latest.zip > /tmp/sealights-java.zip" 2-prepare-java-agent: command: "mkdir /tmp/sealights" command: "unzip /tmp/sealights-java.zip -d /tmp/sealights" 3-set-sealights-permissions: command: "chmod +rwx /tmp/sealights" option_settings: namespace: "aws:elasticbeanstalk:container:tomcat:jvmoptions" option_name: "JVM Options" value: "-javaagent:/tmp/sealights/sl-test-listener.jar -Dsl.tags=beanstalk [-Dsl.labId=<lab ID>]"

Beanstalk instance running multiple Java processes

In this case, a Procfile needs to be configured which defines the JVM configuration on a per-service basis:

  • Ensure the "Include Resources" checkbox is checked for this application, so that the buildSessionId.txt and the sltoken.txt files are packaged into the artifact

    • If unselected, the build session ID and token files need to be defined explicitly within the Java arguments

  • The Test Listener must be deployed onto the Elastic Beanstalk instance. This can be achieved by using the Maven Copy plugin, like described here.

Once the above prerequisites are met, a Procfile needs to be defined:

  • Within the Procfile, you specify the .jar with which SeaLights starts up using the following syntax:

    <service name>: <java command> <java args>

For example:

service: java -javaagent:sl-test-listener.jar -Dsl.tags=beanstalk [-Dsl.labId=<lab ID>] -jar service.jar

You can confirm that the Test Listener is running from the Cockpit -> Agent Monitor screen

  • No labels