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

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

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

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

--branchName

Yes

The source branch of the application

SL_GENERAL_BRANCHNAME

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

--buildName

Yes

The build label/version of the current artifact

SL_GENERAL_BUILDNAME

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

--labId

Yes

CD-only lab id

SL_LABID, SL_SESSION_LABID

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

--binDir

Yes

Path to the scanned folder where all binary files are located

SL_SCAN_BINDIR

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

--includeNamespace

Yes

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

SL_SCAN_INCLUDENAMESPACES

"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

"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

"profiler": {
  "logLevel": 6
}

--profilerLogDir

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

SL_PROFILER_LOGDIRECTORY

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

Sample Commands

Downloading the agent

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

Linux

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

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

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.

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

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

Sample Commands

Downloading the agent

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

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`"

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)"

Sample configuration in a docker file

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"

IIS Application

• Make sure that the publish mode is not “Single file“ or “Portable“.

• Prepare the environment variables below

  Code Block

  COR_ENABLE_PROFILING=1 COR_PROFILER={01CA2C22-DC03-4FF5-8350-59E32A3536BA} COR_PROFILER_PATH=\PathToAgent\sealights-dotnet-agent-windows-self-contained\SL.DotNet.ProfilerLib.Windows_x64.dll COR_PROFILER_PATH_32=\PathToAgent\sealights-dotnet-agent-windows-self-contained\SL.DotNet.ProfilerLib.Windows_x86.dll COR_PROFILER_PATH_64=\PathToAgent\sealights-dotnet-agent-windows-self-contained\SL.DotNet.ProfilerLib.Windows_x64.dll CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={01CA2C22-DC03-4FF5-8350-59E32A3536BA} CORECLR_PROFILER_PATH_32=\PathToAgent\sealights-dotnet-agent-windows-self-contained\SL.DotNet.ProfilerLib.Windows_x86.dll CORECLR_PROFILER_PATH_64=\PathToAgent\sealights-dotnet-agent-windows-self-contained\SL.DotNet.ProfilerLib.Windows_x64.dll SL_PROFILER_INITIALIZECOLLECTOR=1 SL_PROFILER_INITIALIZECOLLECTOR_MODE=cdAgent SL_FEATURES_IDENTIFYMETHODSBYFQN=true SL_PROFILER_BLOCKING_CONNECTION_STARTUP=ASYNC SL_AGENT_PORT=31031 SL_EXE_PATH=\PathToAgent\\sealights-dotnet-agent-windows-self-contained\SL.DotNet.exe SL_SESSION_TOKENFILE=\PathToLogs\scripts\tokens\dev.token useMsProfiler=False SL_GENERAL_BUILDNAME=PICCDAGENT-IIS-5 SL_GENERAL_APPNAME=TestAppWeatherApi SL_GENERAL_BRANCHNAME=main SL_SCAN_BINDIR=c:\inetpub\TestWebApp\ SL_LABID=integ_main_TestAppWeatherApi SL_SCAN_INCLUDENAMESPACES_0=StatelessWebApp.* SL_SCAN_INCLUDEASSEMBLIES=*StatelessWebApp SL_PROFILER_INCLUDEPROCESSFILTER=*TestWebApp* SL_LOGGING_ENABLED=true SL_LogLevel=6 SL_Logging_toFile=true SL_LogDir=\PathToLogs\logs SL_LOGGING_FileName=\PathToLogs\logs\listener_pic

• Set the environment variables to IIS Services in the Windows Registry.

  • For that, open the registry keys Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS and Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC

  • Add a new Multi-String value called Environment

    Image Added

• Restart the IIS Server via the usual iisreset /restart

• Perform the query to the web application to wake it up.

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.

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

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

#!/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

Agent’s Parameters Reference

Mandatory parameters - .Net/Agent

Mandatory parameters - Application specific

Optional parameters

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

Logging parameters

To enable logs, you can set the following parameters