Coverage Listener Mode (Application Under Test)

Using the Go Agent in Coverage Listener Mode

Coverage Listener Mode is used when you want to instrument your Go application to collect code coverage data during testing. The agent monitors your application and reports which lines of code are executed, providing insights into test coverage and code quality.

Overview

The basic workflow for instrumenting your application with the SeaLights Go Agent involves three basic steps:

1. Configuration - Set up agent parameters and generate a Build Session ID

2. Scan and Instrument - Analyze your code and add instrumentation markers

3. Deploy - Run your instrumented application to collect coverage data

These steps are described in more detail below.

---

Steps for Instrumenting an Application () with SeaLights Go Agent

1

Configuration and Build Session ID Generation

The first step configures the agent and generates a Build Session ID (BSID) that uniquely identifies this build in the SeaLights system, using the command ./slgoagent config ...

Minimum Required Parameters for this command:

• --token - Your SeaLights authentication token or path to token file

• --app-name - Name of your application as it should appear in SeaLights

• --branch - Git branch name (defaults to "main" if not specified)

• --build - Build identifier (auto-generated timestamp if not specified)

TIP: We also recommend setting the --lab-id parameter on your Application. This can be set at application runtime, using an environment variable, or it can be set up at this configuration stage.

You can set these parameters in three different ways: CLI flags, environment variables, or configuration file. The examples below demonstrate each approach, using the minimum recommended parameters. For additional configuration options, see the Go Agent Parameter Reference Table.

Example Configurations:

CLI

Example 1: All parameters as CLI flags

./slgoagent config \
  --token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --app-name="shopping-cart-service" \
  --branch="feature-checkout" \
  --build="v1.2.3-build-456" \
  --lab-id="shoppingcart.dev.qa-blue"

Environment variables

Example 2: Using environment variables

export SEALIGHTS_APP_NAME="shopping-cart-service"
export SEALIGHTS_BRANCH="feature-checkout"
export SEALIGHTS_BUILD="v1.2.3-build-456"
export SEALIGHTS_LAB_ID="shoppingcart.dev.qa-blue"

./slgoagent config

Configuration file

Example 3: Using configuration file

Create .slconfig.yaml in your project root:

appName: "shopping-cart-service"
branch: "feature-checkout"
build: "v1.2.3-build-456"
labId: "shoppingcart.dev.qa-blue"

Then run:

./slgoagent config --token="./sltoken-local.txt"

What this command generates:

• Build Session ID (BSID) - Unique identifier linking this build to SeaLights

• build.json file - Contains all configuration that will be used in the following scan step

• Console output - Confirmation of successful configuration and the generated BSID

2

Scan and Instrument the Application Code

This step analyzes your project structure and adds instrumentation markers to track method execution during testing.

Command:

./slgoagent scan

This command does not typically need additional parameters passed with it. Use ./slgoagent scan --help for details

What this command does:

• Scans your project structure and reports it to SeaLights

• Instruments your Go source code with lightweight tracking markers

• Preserves original code logic while adding coverage collection capabilities

• Creates instrumented versions of your source files

Output: The command will show progress as it processes files and adds instrumentation. You'll see output indicating which files are being scanned and instrumented.

NOTE: This command does not typically need additional parameters passed with it. Use ./slgoagent scan --help for details.

3

Run Unit Tests (Optional)

If you have unit tests, run them now using your normal test commands. The SeaLights Go Agent will automatically track coverage during unit test execution because your code is already instrumented.

# Run your unit tests as normal
go test ./...
# or
go test -v ./internal/...
# or your specific test command

Important: SeaLights will automatically collect coverage data during these test runs. No additional configuration is needed for unit test coverage collection. Note that this applies *only* to unit tests. Other test stages must be tracked using a SeaLights Agent or by opening a Manual Test Stage with SeaLights.

4

Deploy the Instrumented Application Code

Deploy the instrumented application to your test environment.

Verification: After deployment, verify that your application is correctly reporting to SeaLights:

1. Log into the SeaLights web interface

2. Navigate to "Cockpit" → "Live Agents Monitor"

3. Look for your application name in the list of active agents

4. Confirm that the status shows your agent as "Connected" or "Active"

If your application appears in the Live Agents Monitor, the integration is working correctly. Coverage data will now be collected when a test execution is opened with SeaLights.

For more information on how Coverage Listener Mode and Test Runner Mode work together, see [PLACEHOLDER LINK TO EXPLANATION OF HOW THE COVERAGE LISTENER AND TEST RUNNER MODES WORK TOGETHER].

---

Using the SeaLights Go Agent with a Lambda Function.

If you are instrumenting an AWS Lambda function, you must configure the agent to run in Light Mode for optimal performance. Lambda functions have strict performance and network requirements that standard agent operation cannot meet.

Required Configuration for Lambda:

• SL_LIGHT_MODE=true - Enables Light Mode for optimized Lambda performance

• SL_COLLECTOR_URL - Specifies the collector endpoint for efficient network routing

These parameters should be set as environment variables in your Lambda function configuration, not during the initial config/instrument steps, to avoid impacting unit test coverage collection.

Why Light Mode for Lambda: Light Mode streamlines the agent to only essential coverage collection, eliminating background processes like heartbeats and remote configuration that can negatively impact Lambda cold start times and execution performance.

For complete technical details and deployment examples, see Deep Dive: AWS Lambda Functions.

---

Troubleshooting

Common Issues:

• "token is required" error: Ensure your token parameter is set correctly and the token file exists

• Network connectivity issues: Check firewall settings and proxy configuration

• "no test functions were instrumented, this might cause the agent to not run in Unit Test mode" warning: This occurs when your unit tests use Go build tags but the buildTags parameter is not configured. Add the --build-tags parameter to your config command with the appropriate tags (e.g., --build-tags="unit")

• Application not appearing in Live Agents Monitor: Verify network connectivity and check application logs for SeaLights-related errors