Pivotal Cloud Foundry (PCF) Support

Adding the Sealights Java agent into your Pivotal Cloud Foundry environment (formerly VMWare Tanzu Application Services) is done by using the standard CloudFoundry Java buildpack 4.39 or later.

Complimentary information is detailed in https://github.com/cloudfoundry/java-buildpack/blob/main/docs/framework-sealights_agent.md

Installing CF Java buildpack

The Java Buildpack is a Cloud Foundry buildpack for running JVM-based applications and is configured in one of the following ways:

In the manifest.yml of your app, add the CloudFoundry Java buildpack

---
applications:
-  name: yourApp
    buildpacks:
    - https://github.com/cloudfoundry/java-buildpack

Add the buildpack through the command line

cf push -b https://github.com/cloudfoundry/java-buildpack

If you need to create an offline buildpack without network access, you can do so following the instructions here: https://github.com/cloudfoundry/java-buildpack#offline-package

Configuring the Sealights service in Java Buildpack

Setting up the Sealights Java buildpack integration involves a few straightforward steps:

Create a Sealights user-provided service and define its general settings (typically the token).
Bind your application to the Sealights service.
Define Sealights-specific parameters for your application (e.g., lab_id, proxy, etc.).
Restage the application to apply the changes.

While these steps can be automated through a manifest file using Cloud Foundry's native support for declaring services and environment variables, the following sections will focus on the equivalent CLI-based workflow, which is more commonly used in CI/CD automation scripts.

Create your Sealights User-Provided service

Create a Sealights User-Provided Service and configure it with an agent token. This should be done once, before configuring the first application, as it allows you to manage the token at the service level.

cf cups sealights-java -p '{"token":"ey…"}'

A different name for the user-provided service may be used, but it MUST include the word sealights (lowercase) for the integration to work

The token may later be changed using: cf update-user-provided-service sealights-java -p '{"token":"ey…"}' (or via the command shortcut cf uups)
If you need to use a different token per application, you can also define it as part of the application parameters (see below)

Bind your application to your Sealights service

Bind the User-Provided Service with your application using the following command

cf bind-service [app name] sealights-java

Defining the Sealight's specific parameters

If the build session ID, lab ID, proxy, or other settings need to be configured, you may either use one of the following options:

hard-code them in manifest.yml:

env:
  JBP_CONFIG_SEALIGHTS_AGENT: '{lab_id: yourLabId, proxy: "http://myproxy.mycompany.int"}'

pass them as environment variables for the application via a dedicated command:

cf set-env [my-application] JBP_CONFIG_SEALIGHTS_AGENT '{lab_id: "myLabId", proxy: "http://myproxy.mycompany.int"}'

set up as environment variables via your administrative console:

JBP_CONFIG_SEALIGHTS_AGENT must be declared as a User-Provided Environment Variable (specific to the app instance) and not at the service level (such as Credential parameters, for example).

Available configuration keys are:

Name

Description

build_session_id

Generating a session IDfor the application. Leave blank to use the value embedded in the jar/war artifacts

proxy

Specify an HTTP proxy used to communicate with the Sealights backend. This option is required when a corporate network prohibits communication with our cloud services. The default is to have no proxy configured and does not inherit from http_proxy/https_proxy or http.proxyHost/https.proxyHost, you must set this specifically if a proxy is needed.

lab_id

Specify a Sealights Lab ID Running Tests in Parallel (Lab Id)

auto_upgrade

Enable/disable agent auto-upgrade. Off by default.

version

The version of Auto-reconfiguration to use. Candidate versions can be found in this listing. If auto_upgrade is turned on, a different version may be downloaded and used at runtime

Restage Application

To apply changes, you have to publish your application again, or simply restage it with the command restage

cf restage [app name]

When the application is up and running and the Sealights Listener agent is properly configured, you can validate that it is running and communicating with your dashboard account from the Cockpit -> Live Agents Monitor screen.

How to download the SL agent to CF from a Custom Repository

By default, the Sealights PCF buildpack fetches the agent version from the official repository index at https://agents.sealights.co/pcf/index.yml. This index.yml file maps each agent version to its corresponding download URL, for example:

#... (older)
4.0.2561: https://agents.sealights.co/sealights-java/sealights-java-4.0.2561.zip
4.0.2565: https://agents.sealights.co/sealights-java/sealights-java-4.0.2565.zip
4.0.2570: https://agents.sealights.co/sealights-java/sealights-java-4.0.2570.zip
#... (newer)

In scenarios where direct access to the default Sealights repository is restricted (e.g., due to internal security policies), you can configure the buildpack to use a self-hosted, customized list of agent URLs, allowing the agent to be downloaded from a custom repository (e.g., an internal Artifactory server) without the need to repackage the buildpack.

Here are the recommended steps to follow:

Create and host your custom version of the index.yml file that maps agent versions to internal URLs, for example:

#...
4.0.2570: https://my-artifactory-server.mycompany.int/sealights/agents/java/sealights-java-4.0.2570.zip
#...

Alternatively, you can also point to the agents endpoint mirrored on your custom dashboard instance (your-domain.sealights.co) if accessible from your CF instances:

#...
4.0.2570: https://<your-custom-domain>.sealights.co/agents/sealights-java/sealights-java-4.0.2570.zip
#...

Ensure this index.yml file is publicly accessible to the buildpack at a custom URL, e.g., https://my-file-server.mycompany.int/sealights-pcf/index.yml.

Configure the Sealights buildpack to use your custom repository definition by setting the base URL to your index.yml file as the repository_root in the JBP_CONFIG_SEALIGHTS_AGENT environment variable at the application level (developer) or platform level (operator):

cf set-env my-app JBP_CONFIG_SEALIGHTS_AGENT '{ repository_root: "https://my-file-server.mycompany.int/sealights-pcf", lab_id: "myLabId"}'

This tells the buildpack to fetch the agent metadata from your custom index.yml.

With the custom configuration set, push or restage your application as usual.

Your custom index.yml only needs to include the versions you intend to use.
The repository_root must be the base path containing the index.yml file (without the filename itself).
No changes to the actual buildpack source or packaging are required.

Sample configuration

Sample `Manifest.yml`

applications:
  - name: my-app
    memory: 1G
    buildpacks:
      - https://github.com/cloudfoundry/java-buildpack
    env:
      JBP_CONFIG_SEALIGHTS_AGENT: >
        {lab_id: "${SL_LAB_ID}", proxy: "${CF_PROXY}"}
    services:
      - sealights-java

Sample Deployment Script

#!/bin/bash
set -e

# Configurable values
APP_NAME="my-app"
SEALIGHTS_SERVICE="sealights-java"

# Retrieve secrets from a secrets vault (e.g., HashiCorp Vault)
export SL_LAB_ID="myLabId"
export CF_PROXY="http://myproxy.mycompany.int"
export SEALIGHTS_TOKEN=$(vault kv get -field=token secret/sealights)  # Replace with your vault command

# Create or update the user-provided service for Sealights
cf cups $SEALIGHTS_SERVICE -p '{"token":"'"$SEALIGHTS_TOKEN"'"}'

# Check for manifest.yml presence
if [ -f "manifest.yml" ]; then
  echo "manifest.yml found. Deploying using manifest..."
  cf push
else
  echo "manifest.yml not found. Proceeding with manual deployment..."
  cf push $APP_NAME -b https://github.com/cloudfoundry/java-buildpack
  # Set Sealights environment variables
  cf set-env $APP_NAME JBP_CONFIG_SEALIGHTS_AGENT '{lab_id: "'"$SL_LAB_ID"'", proxy: "'"$CF_PROXY"'"}'
  cf bind-service $APP_NAME $SEALIGHTS_SERVICE
  cf restage $APP_NAME
fi

# Optionally display recent logs and status
cf logs $APP_NAME --recent
cf app $APP_NAME

Troubleshooting Sealights Buildpack Configuration

If your application is not instrumented as expected or you suspect issues with the Sealights buildpack integration, follow these recommended steps to identify and resolve common configuration problems.

Verify Sealights Buildpack Configuration

Ensure that all required Sealights-related environment variables are defined (e.g., JBP_CONFIG_SEALIGHTS_AGENT, etc.).
Confirm that the Sealights service is correctly bound to the application.

Analyze Application Logs

Check the application logs using cf logs <your-app-name>.
Search for the keyword sealights to identify log entries related to the agent or buildpack.
Review any errors or warnings related to agent download, initialization, or configuration.

Connect to the Running CF Instance

Use cf ssh <your-app-name> to access the application container and perform the following validations:

Run the standard ps -ef | grep java command to find and validate the startup parameters of the Java process of your application. Look for the Sealights Java agent in the JVM parameters (e.g., -javaagent:/path/to/sealights-java-agent.jar).
Run the standard env | grep SEALIGHTS command to find and check the required environment variables. Ensure that Sealights-specific variables (e.g., JBP_CONFIG_SEALIGHTS_AGENT) are correctly set in the runtime environment.
Verify that the Sealights agent JAR was downloaded successfully and is not corrupted. If missing, try downloading the agent manually to test connectivity, then unzip the archive and inspect the content if needed.
If your application was built in your CI with Sealights Maven or Gradle plugins, ensure the buildSessionId.txt and sltoken.txt files are bundled within your deployed application. Depending on your setup, these files should reside in the application's working directory or embedded within the JAR.

PreviousRunning test listener with JMeter NextAWS Lambda Support

Last updated 2 days ago

Was this helpful?

Installing CF Java buildpack

Configuring the Sealights service in Java Buildpack

Create your Sealights User-Provided service

Bind your application to your Sealights service

Defining the Sealight's specific parameters

Restage Application

How to download the SL agent to CF from a Custom Repository

Sample configuration

Sample Manifest.yml

Sample Deployment Script

Troubleshooting Sealights Buildpack Configuration

Verify Sealights Buildpack Configuration

Analyze Application Logs

Connect to the Running CF Instance

Sample `Manifest.yml`