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:

Configuration - Set up agent parameters and generate a Build Session ID
Scan and Instrument - Analyze your code and add instrumentation markers
Deploy - Run your instrumented application to collect coverage data

These steps are described in more detail below.

Steps for Instrumenting an Application (AUT) with SeaLights Go Agent

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
--appName - Name of your application as it should appear in SeaLights
--branchName - Git branch name (defaults to "main" if not specified)
--buildName - 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:

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"

Example 2: Using environment variables

export SL_APP_NAME="shopping-cart-service"
export SL_BRANCH="feature-checkout"
export SL_BUILD="v1.2.3-build-456"

./slgoagent config

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"

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

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.

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.

Deploy the Instrumented Application Code

Deploy the instrumented application to your test environment.

Best Practice: Set SL_LAB_ID on the runtime environment We recommend setting the lab id on your application via environment variable in the runtime environment to allow greater flexibility in your CI/CD workflows.

# On the runtime environment
export SL_LAB_ID="shoppingcart.dev.qa-blue"

However, if your workflows do not allow you to easily set runtime env vars, this parameter can also be set using a CLI flag during the slgoagent config command.

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

Log into the SeaLights web interface
Navigate to "Cockpit" → "Live Agents Monitor"
Look for your application name in the list of active agents
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.

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

BEST PRACTICE: 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 --tags parameter to your config command with the appropriate tags (e.g., --tags="unit")
Application not appearing in Live Agents Monitor: Verify network connectivity and check application logs for SeaLights-related errors

PreviousGo Agent: How to use NextQuickstart: Add Go Agent to AUT

Last updated 2 months ago

Was this helpful?