/
SeaLights CD Agent for .Net Application

SeaLights CD Agent for .Net Application

Owned by Marc Amouyal
Last updated: Nov 05, 2024
6 min read

 

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

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

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

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

  4. Add the CD agent to your environment to attach it as a Profiler to your Application Under Test.

  5. Set the relevant parameters and/or environment variables to be used (See samples below)

 

 

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.

Sample Commands

Downloading the agent

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

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

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

Sample configuration in a docker file

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" ENV SL_FEATURES_IDENTIFYMETHODSBYFQN="true" ENV SL_SESSION_TOKENFILE=/sealights/sltoken.txt ARG BUILD_NUMBER 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"

Sample K8s yaml

spec: initContainers: - name: sealights-dotnet-agent image: ubuntu:latest imagePullPolicy: IfNotPresent command: ["/bin/sh", "-c"] args: - | wget -nv -O sealights-dotnet-agent-linux.tar.gz https://agents.sealights.co/dotnetcore/latest/sealights-dotnet-agent-linux-self-contained.tar.gz tar -xzf ./sealights-dotnet-agent-linux.tar.gz --directory /sealights echo "[Sealights] .NetCore Agent version is: $(cat /sealights/version.txt)" volumeMounts: - mountPath: /sealights name: sealights-dotnet-agent-file containers: - name: your-app-service-container # other container configurations # [...] env: ### SL Profiler - Generic vars - name: SL_TOKEN secretKeyRef: name: sealights key: SL_TOKEN - name: CORECLR_ENABLE_PROFILING value: "1" - name: CORECLR_PROFILER value: "{3B1DAA64-89D4-4999-ABF4-6A979B650B7D}" - name: CORECLR_PROFILER_PATH_32 value: /sealights/libSL.DotNet.ProfilerLib.Linux.so - name: CORECLR_PROFILER_PATH_64 value: /sealights/libSL.DotNet.ProfilerLib.Linux.so - name: SL_PROFILER_INITIALIZECOLLECTOR_MODE value: "cdAgent" - name: SL_PROFILER_INITIALIZECOLLECTOR value: 1 - name: SL_PROFILER_BLOCKING_CONNECTION_STARTUP value: "ASYNC" - name: SL_FEATURES_IDENTIFYMETHODSBYFQN value: "true" ### SL Profiler - Env Specific vars - name: SL_SCAN_BINDIR value: "/app" - name: SL_LABID value: "integ_poc_sl" ### SL Profiler - App Specific vars - name: SL_GENERAL_APPNAME value: "myproject-myapp-service" - name: SL_GENERAL_BRANCHNAME value: "sample-branch" - name: SL_GENERAL_BUILDNAME value: "1.0.2" - name: SL_SCAN_INCLUDENAMESPACES_0 value: "myproject.*" - name: SL_SCAN_INCLUDEASSEMBLIES #reduce files to scan to speed up startup value: "*myproject*" volumeMounts: - mountPath: /sealights name: sealights-dotnet-agent-file volumes: - name: sealights-dotnet-agent-file emptyDir: {}

IIS Application

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

  • Prepare the environment variables below (absolute paths are better)

    COR_ENABLE_PROFILING=1 COR_PROFILER={01CA2C22-DC03-4FF5-8350-59E32A3536BA} COR_PROFILER_PATH=C:\AbsolutePathToAgentFolder\SL.DotNet.ProfilerLib.Windows_x64.dll COR_PROFILER_PATH_32=C:\AbsolutePathToAgentFolder\SL.DotNet.ProfilerLib.Windows_x86.dll COR_PROFILER_PATH_64=C:\AbsolutePathToAgentFolder\SL.DotNet.ProfilerLib.Windows_x64.dll CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={01CA2C22-DC03-4FF5-8350-59E32A3536BA} CORECLR_PROFILER_PATH_32=C:\AbsolutePathToAgentFolder\SL.DotNet.ProfilerLib.Windows_x86.dll CORECLR_PROFILER_PATH_64=C:\AbsolutePathToAgentFolder\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=C:\AbsolutePathToAgentFolder\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

  • 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

Variable

Required

Description

Property (CLI)

Variable

Required

Description

Property (CLI)

COR_ENABLE_PROFILING

Yes

Instructs the runtime to enable profiling. Set to: 1

N/A

COR_PROFILER

Yes

Instructs the runtime which profiler to use. Set to: {3B1DAA64-89D4-4999-ABF4-6A979B650B7D}

N/A

COR_PROFILER_PATH_32

Yes

Instructs the runtime where to find the 32 bit version of the profiler
Set to the path of libSL.DotNet.ProfilerLib.Linux.so

N/A

COR_PROFILER_PATH_64

Yes

Instructs the runtime where to find the 64 bit version of the profiler
Set to the path of libSL.DotNet.ProfilerLib.Linux.so

N/A

CORECLR_ENABLE_PROFILING

Yes

Instructs the runtime to enable profiling for .NET Core
Set to: 1

N/A

CORECLR_PROFILER

Yes

Instructs the runtime which profiler to use for .NET Core
Set to: {3B1DAA64-89D4-4999-ABF4-6A979B650B7D}

N/A

CORECLR_PROFILER_PATH_32

Yes

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

N/A

CORECLR_PROFILER_PATH_64

Yes

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

N/A

SL_PROFILER_INITIALIZECOLLECTOR

Yes

Instructs the Sealights profiler to initialize its own collector when starting up
Set to: 1

N/A

SL_PROFILER_INITIALIZECOLLECTOR_MODE

Yes

Instructs the Sealights profiler in which mode to start up
Set to: cdAgent

cdAgent

SL_FEATURES_IDENTIFYMETHODSBYFQN

Yes

Set to true

--identifyMethodsByFQN

Mandatory parameters - Application specific

Env variable

Required

Description

Property (CLI)

Env variable

Required

Description

Property (CLI)

SL_SESSION_TOKENFILE or SL_SESSION_TOKEN

Yes

Provides the Sealights agent the token to work with
Set to the token itself or the path to the token file

--token or --tokenFile

SL_GENERAL_APPNAME

Yes

Name of the target application

--appName

SL_GENERAL_BRANCHNAME

Yes

The source branch of the application

--branchName

SL_GENERAL_BUILDNAME

Yes

The build label/version of the current artifact

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.

--buildName

SL_LABID, SL_SESSION_LABID

Yes

CD-only lab id

--labId

SL_SCAN_BINDIR

Yes

Path to the scanned folder where all binary files are located

--binDir

 

SL_SCAN_INCLUDENAMESPACES

Yes

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

--includeNamespace

Optional parameters

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

Env variable

Description

Parameter (CLI)

Env variable

Description

Parameter (CLI)

SL_SCAN_EXCLUDENAMESPACES

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

Default value: System.*, Microsoft.*

--excludeNamespace

SL_SCAN_INCLUDEFILES

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

Default value: *.dll,*.exe

--include

SL_SCAN_EXCLUDEFILES

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

--exclude

SL_SCAN_INCLUDEASSEMBLIES

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

--includedAssemblies

SL_SCAN_EXCLUDEASSEMBLIES

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

Default value: mscorlib, System., Microsoft.

--excludedAssemblies

SL_SCAN_SRCROOTDIR

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

--srcRootDir

SL_PROFILER_TARGET

The name of the target application that will be started

--target

SL_PROFILER_TARGETARGS

Arguments to be passed to the target process

--targetArgs

SL_PROFILER_WORKINGDIR

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

--workingDir

Logging parameters

To enable logs, you can set the following parameters

Env variable

Description

Parameter (CLI)

Env variable

Description

Parameter (CLI)

SL_LOGGING_ENABLED

Set to true to enable logging to the console

 

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_LogDir

Folder to save the log files to

 

SL_LOGGING_FileName

File name to save the log to

 

Related content