Table of Contents

minLevel	1
maxLevel	2

Onboarding the .Net 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.

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. Please refer to the dedicated section below for details.
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 environment to attach it as a Profiler to your Application Under Test.
Set the relevant parameters and/or environment variables to be used (See samples below)

Tip
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.

Spinning up with environment variables


`COR_ENABLE_PROFILING`	Instructs the runtime to enable profiling Set to: `1`
`COR_PROFILER`	Instructs the runtime which profiler to use Set to: `{3B1DAA64-89D4-4999-ABF4-6A979B650B7D}`
`COR_PROFILER_PATH_32`	Instructs the runtime where to find the 32 bit version of the profiler Set to the path of `libSL.DotNet.ProfilerLib.Linux.so`
`COR_PROFILER_PATH_64`	Instructs the runtime where to find the 64 bit version of the profiler Set to the path of `libSL.DotNet.ProfilerLib.Linux.so`
`CORECLR_ENABLE_PROFILING`	Instructs the runtime to enable profiling for .NET Core Set to: `1`
`CORECLR_PROFILER`	Instructs the runtime which profiler to use for .NET Core Set to: `{3B1DAA64-89D4-4999-ABF4-6A979B650B7D}`
`CORECLR_PROFILER_PATH_32`	Instructs the runtime where to find the 32 bit version of the profiler for .NET Core Set to the path of `libSL.DotNet.ProfilerLib.Linux.so`
`CORECLR_PROFILER_PATH_64`	Instructs the runtime where to find the 64 bit version of the profiler for .NET Core Set to the path of `libSL.DotNet.ProfilerLib.Linux.so`
`SL_PROFILER_INITIALIZECOLLECTOR`	Instructs the Sealights profiler to initialize its own collector when starting up Set to: `1`
`SL_PROFILER_INITIALIZECOLLECTOR_MODE`	Instructs the Sealights profiler in which mode to start up Set to: `cdAgent`
`SL_PROFILER_BLOCKING_CONNECTION_STARTUP`	Instructs the Sealights profiler what blocking connection type to use during startup Set to: `ASYNC`
`SL_SESSION_TOKENFILE` or `SL_SESSION_TOKEN`	Provides the Sealights agent the token to work with Set to the token itself or the path to the token file
`SL_GENERAL_APPNAME`	Name of the component
`SL_GENERAL_BRANCHNAME`	Source branch of the component
`SL_GENERAL_BUILDNAME`	The build label/version of the current artifact
`SL_LABID`	Identifier of the current application under test. If this is part of multiple components, then it should be a “CD Only” integration lab ID If it is a stand alone component, then it should be a unique string
`SL_SCAN_BINDIR`	Path to the scanned folder where all binary files are located
`SL_SCAN_INCLUDENAMESPACES`	Comma-separated list of namespaces to include in the scan. Supports wildcard (`*` = any string, `?` = any character) characters.
`SL_SCAN_INCLUDEASSEMBLIES`	Comma-separated list of namespaces to include in the scan. Supports wildcard (`*` = any string, `?` = any character) characters.
`SL_FEATURES_IDENTIFYMETHODSBYFQN`	Set to `true`
`SL_LogDir`	Folder to save the log files to
`SL_LogLevel`	Log level. Default and Recommended value is `6` `0`=None `3`=Errors `4`=Warnings `6`=Info (Light Debug) `7`=Debug(Full)
`SL_Logging_toFile`	Set to `true` to enable logging to a file
`SL_LOGGING_ENABLED`	Set to `true` to enable logging to the console
`SL_LOGGING_FileName`	File name to save the log to

Sample configuration in a docker file

Code Block

ENV COR_ENABLE_PROFILING=1
ENV COR_PROFILER="{3B1DAA64-89D4-4999-ABF4-6A979B650B7D}"
ENV COR_PROFILER_PATH_32=/sealights/libSL.DotNet.ProfilerLib.Linux.so
ENV COR_PROFILER_PATH_64=/sealights/libSL.DotNet.ProfilerLib.Linux.so
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER="{3B1DAA64-89D4-4999-ABF4-6A979B650B7D}"
ENV CORECLR_PROFILER_PATH_32=/sealights/libSL.DotNet.ProfilerLib.Linux.so
ENV CORECLR_PROFILER_PATH_64=/sealights/libSL.DotNet.ProfilerLib.Linux.so
ENV SL_PROFILER_INITIALIZECOLLECTOR=1
ENV SL_PROFILER_INITIALIZECOLLECTOR_MODE="cdAgent"
ENV SL_PROFILER_BLOCKING_CONNECTION_STARTUP="ASYNC"

ARG BUILD_NUMBER
ENV SL_SESSION_TOKENFILE=/sealights/sltoken.txt
ENV SL_GENERAL_APPNAME="otel_cartservice"
ENV SL_GENERAL_BRANCHNAME="main"
ENV SL_GENERAL_BUILDNAME=$BUILD_NUMBER
ENV SL_LABID="my_lab"
ENV SL_SCAN_BINDIR="/app"
ENV SL_SCAN_INCLUDENAMESPACES_0="cartservice.*"
ENV SL_SCAN_INCLUDEASSEMBLIES="*cartservice"
ENV SL_FEATURES_IDENTIFYMETHODSBYFQN="true"

Agent’s Parameters Reference

Mandatory parameters

Property (CLI)

Required

Description

Env variable

JSON

--appName

Yes

Name of the target application

SL_GENERAL_APPNAME

Code Block

language	json

"general": {
  "appName": ""
}

--branchName

Yes

The source branch of the application

SL_GENERAL_BRANCHNAME

Code Block

language	json

"general": {
  "branchName": ""
}

--buildName

Yes

The build label/version of the current artifact

Note

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_GENERAL_BUILDNAME

Code Block

language	json

"general": {
  "buildName": ""
}

--labId

Yes

CD-only lab id

SL_LABID, SL_SESSION_LABID

Code Block

language	json

"general": {
  "labId": ""
}

--binDir

Yes

Path to the scanned folder where all binary files are located

SL_SCAN_BINDIR

Code Block

language	json

"general": {
  "binDir": ""
}

--includeNamespace

Yes

Comma-separated list of namespaces to include in the scan.
Supports wildcard (* = any string, ? = any character) characters.

SL_SCAN_INCLUDENAMESPACES

Code Block

language	json

"general": {
  "includeNamespaces": ""
}

Optional parameters

These parameters may be required due to your specific configuration or environment’s limitations (e.g., proxy).

Property

Description

Env variable

JSON

--excludeNamespace

Comma-separated list of namespaces to exclude from the scan. Supports wildcard (* = any string, ? = any character) characters.

Default value: System.*, Microsoft.*

SL_SCAN_EXCLUDENAMESPACES

--include

Comma-separated list of files to include in scan. Supports wildcard (* = any string, ? = any character) characters.

Default value: *.dll,*.exe

SL_SCAN_INCLUDEFILES

--exclude

Comma-separated list of files to exclude from the scan. Supports wildcard (* = any string, ? = any character) characters.
Default value: System.", "Microsoft.

SL_SCAN_EXCLUDEFILES

--includedAssemblies

Comma-separated list of assemblies to include. Supports wildcard (* = any string, ? = any character) characters.

SL_SCAN_INCLUDEASSEMBLIES

--excludedAssemblies

Comma-separated list of assemblies to exclude from the scan. Supports wildcard (* = any string, ? = any character) characters.

Default value: mscorlib, System., Microsoft.

SL_SCAN_EXCLUDEASSEMBLIES

--srcRootDir

The project source root directory, where all paths will be made relative to

SL_SCAN_SRCROOTDIR

Code Block

language	json

"scan": {
  "srcRootDir": ""
}

--target

The name of the target application that will be started

SL_PROFILER_TARGET

--targetArgs

Arguments to be passed to the target process

SL_PROFILER_TARGETARGS

--workingDir

The path to the working directory. By default, it’s using current working directory.

SL_PROFILER_WORKINGDIR

Logging parameters

To enable logs, you can set the following parameters

Parameter (CLI)

Description

Env variable

JSON

--profilerLogLevel

Log level. Default and Recommended value is 6

0=None
3=Errors
4=Warnings
6=Info (Light Debug)
7=Debug(Full)

SL_PROFILER_LOGLEVEL

Code Block

language	json

"profiler": {
  "logLevel": 6
}

--profilerLogDir

Enables logging profiler data to file. Requires LogLevel to be specified.

SL_PROFILER_LOGDIRECTORY

Code Block

language	json

"profiler": {
  "logDirectory": ""
}

Sample Commands

Downloading the agent

Info
The different available options to download the agent are documented in a dedicated central page: https://sealights.atlassian.net/l/cp/g0omvaoL

For example, you can use the following commands to automate the process

Linux

Code Block

language	bash

wget -nv -O sealights-dotnet-agent-linux.tar.gz https://agents.sealights.co/dotnetcore/latest/sealights-dotnet-agent-linux-self-contained.tar.gz
mkdir sl-dotnet-agent && tar -xzf ./sealights-dotnet-agent-linux.tar.gz --directory ./sl-dotnet-agent
echo "[Sealights] .NetCore Agent version is: `cat ./sl-dotnet-agent/version.txt`"

Windows

Code Block

language	bash

iwr -OutFile sealights-dotnet-agent.zip -UseBasicParsing -Uri https://agents.sealights.co/dotnetcore/latest/sealights-dotnet-agent-windows-self-contained.zip
Expand-Archive .\sealights-dotnet-agent.zip -DestinationPath sl-dotnet-agent -Force
Write-Output "[Sealights] .NetCore Agent version is: $(Get-Content .\sl-dotnet-agent\version.txt)"

Configuration commands

Table of Contents

minLevel	3
maxLevel	7
exclude	parameters

Simple Web App (Desktop, Windows)

This simple use case illustrates how to collect coverage with the CD agent from a web application started without parameters.

Code Block

language	powershell

C:\Sealights\Agent\SL.DotNet.exe cdAgent --appName "TestApp" --branchName "main" --buildName "1.16.10" --labId "integ_demo_DesktopWeatherApp" \
    --binDir "C:\Program Files\WeatherApi" --includeNamespace "WeatherApi*" --target "C:\Program Files\WeatherApi\WeatherApi.exe"

Microservice (Alpine-based docker file)

DockerFile

Code Block

FROM mcr.microsoft.com/dotnet/runtime:6.0-alpine

WORKDIR /app
COPY --from=build /app/out .
COPY Scripts/start-app.sh .

# Sealights - install prereq, agent, token, bsid
# Best practice it to mount a pre-existing sealights directory depending on the environment (test or prod)
RUN mkdir -p /sealights/{agent,logs}
RUN wget -nv -O sealights-dotnet-agent-alpine.tar.gz https://agents.sealights.co/dotnetcore/latest/sealights-dotnet-agent-alpine-self-contained.tar.gz
RUN tar -xzf ./sealights-dotnet-agent-alpine.tar.gz --directory /sealights/agent
COPY ["SeaLights/sltoken.txt", "/sealights/"]
RUN chmod -R 777 /sealights

# Set the script as the entrypoint
ENTRYPOINT ["sh", "start-app.sh", "YourAppName.dll"]

Startup script

Code Block

language	bash

#!/bin/sh
# Check if sealights folder exists
if [ -d "/app/sealights/" ]; then
    /app/sealights/agent/SL.DotNet cdAgent --appName ms-gateway-api --branchName poc --buildName $(cat /app/version.txt) \
                  --binDir /app --includeNamespace MyCompany.* --target dotnet --targetArgs $1 --workingDir /app \
                  --identifyMethodsByFqn --profilerLogLevel 6 --profilerLogDir /app/sealights/logs --labId integ_POC_DemoApp
else
    dotnet $1
fi

Versions Compared

Old Version 10

New Version 11

Key

Onboarding the .Net CD Agent

Configuration steps

Spinning up with environment variables

Agent’s Parameters Reference

Mandatory parameters

Optional parameters

Logging parameters

Sample Commands

Downloading the agent

Configuration commands

Simple Web App (Desktop, Windows)

Microservice (Alpine-based docker file)

Page Comparison

Versions Compared

Old Version 10

New Version 11

Key

Onboarding the .Net CD Agent

Configuration steps

Spinning up with environment variables

Agent’s Parameters Reference

Mandatory parameters

Optional parameters

Logging parameters

Sample Commands

Downloading the agent

Configuration commands

Simple Web App (Desktop, Windows)

Microservice (Alpine-based docker file)