Table of Contents | ||||
---|---|---|---|---|
|
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
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. |
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 | ||
---|---|---|
| ||
"general": {
"appName": ""
} |
--branchName
Yes
The source branch of the application
SL_GENERAL_BRANCHNAME
Code Block | ||
---|---|---|
| ||
"general": {
"branchName": ""
} |
--buildName
Yes
The build label/version of the current artefact
SL_GENERAL_BUILDNAME
Code Block | ||
---|---|---|
| ||
"general": {
"buildName": ""
} |
--labId
Yes
CD-only lab id
SL_LABID
, SL_SESSION_LABID
Code Block | ||
---|---|---|
| ||
"general": {
"labId": ""
} |
--binDir
Yes
Path to the scanned folder where all binary files are located
SL_SCAN_BINDIR
Code Block | ||
---|---|---|
| ||
"general": {
"binDir": ""
} |
--includeNamespace
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 |
| |||||
---|---|---|---|---|---|---|
Windows |
|
Sample configuration in a docker file
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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)
Code Block language powershell 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
andComputer\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.
Code Block | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
#!/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) |
---|---|---|---|
| Yes | Instructs the runtime to enable profiling. Set to: | N/A |
| Yes | Instructs the runtime which profiler to use. Set to: | N/A |
| Yes | Instructs the runtime where to find the 32 bit version of the profiler | N/A |
| Yes | Instructs the runtime where to find the 64 bit version of the profiler | N/A |
| Yes | Instructs the runtime to enable profiling for .NET Core | N/A |
| Yes | Instructs the runtime which profiler to use for .NET Core | N/A |
| Yes | Instructs the runtime where to find the 32 bit version of the profiler for .NET Core | N/A |
| Yes | Instructs the runtime where to find the 64 bit version of the profiler for .NET Core | N/A |
| Yes | Instructs the Sealights profiler to initialize its own collector when starting up | N/A |
| Yes | Instructs the Sealights profiler in which mode to start up |
|
| Yes | Set to |
|
Mandatory parameters - Application specific
Env variable | Required | Description | Property (CLI) | ||
---|---|---|---|---|---|
| Yes | Provides the Sealights agent the token to work with |
| ||
| Yes | Name of the target application |
| ||
| Yes | The source branch of the application |
| ||
| Yes | The build label/version of the current artifact
|
| ||
| Yes | CD-only lab id |
| ||
| Yes | Path to the scanned folder where all binary files are located |
| ||
| Yes | Comma-separated list of namespaces to include in the scan. |
SL_SCAN_INCLUDENAMESPACES
Code Block | ||
---|---|---|
| ||
"general": {
"includeNamespaces": ""
} |
|
Optional parameters
These parameters may be required due to your specific configuration or environment’s limitations (e.g., proxy).
Env variable | Description |
---|
--excludeNamespace
Parameter (CLI) | ||
---|---|---|
| Comma-separated list of namespaces to exclude from the scan. Supports wildcard ( Default value: |
|
|
--include
| Comma-separated list of files to include in scan. Supports wildcard ( Default value: |
|
|
--exclude
| Comma-separated list of files to exclude from the scan. Supports wildcard ( |
|
|
--includedAssemblies
| Comma-separated list of assemblies to include. Supports wildcard ( |
|
|
--excludedAssemblies
| Comma-separated list of assemblies to exclude from the scan. Supports wildcard ( Default value: |
|
|
--srcRootDir
| The project source root directory, where all paths will be made relative to |
|
|
Code Block | ||
---|---|---|
| ||
"scan": {
"srcRootDir": ""
} |
--target
| The name of the target application that will be started |
|
|
--targetArgs
| Arguments to be passed to the target process |
|
|
--workingDir
| The path to the working directory |
SL_PROFILER_WORKINGDIR
. By default, it’s using current working directory. |
|
Logging parameters
To enable logs, you can set the following parameters
--profilerLogLevel
Env variable | Description | Parameter (CLI) |
---|
Description
Env variable
JSON
| Set to | |
| Log level. Default and Recommended value is
| |
|
|
Code Block | ||
---|---|---|
| ||
"profiler": {
"logLevel": 6
} |
--profilerLogDir
Enables logging profiler data to file. Requires LogLevel to be specified.
SL_PROFILER_LOGDIRECTORY
Code Block | ||
---|---|---|
| ||
"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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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 | ||||||
---|---|---|---|---|---|---|
|
Simple Web App
This simple use case illustrates how to collect coverage with the CD agent from a web application started without parameters.
| Set to | |
| Folder to save the log files to | |
| File name to save the log to |