Configuring the Profiler-Initiated Collector

Why use the Profiler-Initiated Collector approach?

There are multiple cases when there is no suitable place in the pipeline to call explicit commands to set and start the Coverage Collector:

docker container requires changes to the entry point and replacing a single command with a more complicated script
Azure environment - there is no place where we can tell Azure to start the collector before the IIS worker
PCF environment also has some complications with stopping BGTL
Azure DevOps environment with TestSuits doesn’t allow to override the test runner command.

To avoid explicit execution of the collector, the profiler can start the detached process of the collector on initialization and connect to it without providing CLI args for the collector. All collector configurations should be set over env variables or using the configuration file. Once the profiled process is finished, the profiler will signal the collector to stop.

This scenario is valid only if the profiler is instructed to use the PIC feature over the env variable:

SL_PROFILER_INITIALIZECOLLECTOR=1

When working with containers that you do not want to modify by adding the Sealights Agent to it, we recommend to mount a folder to thecontainer with the agent there and simply provide the path to the mounted directory.

Agent Setup

To instruct the profiler to start the collector, the target process should have a set of environmental variables:

# .Net Legacy
[Environment]::SetEnvironmentVariable("COR_ENABLE_PROFILING", "1", "Machine")
[Environment]::SetEnvironmentVariable("COR_PROFILER", "{01CA2C22-DC03-4FF5-8350-59E32A3536BA}", "Machine")
[Environment]::SetEnvironmentVariable("COR_PROFILER_PATH_32", "path\to\SL.DotNet.ProfilerLib.Windows_x86.dll", "Machine")
[Environment]::SetEnvironmentVariable("COR_PROFILER_PATH_64", "path\to\SL.DotNet.ProfilerLib.Windows_x64.dll", "Machine")
# .NetCore
[Environment]::SetEnvironmentVariable("CORECLR_ENABLE_PROFILING", "1", "Machine")
[Environment]::SetEnvironmentVariable("CORECLR_PROFILER", "{01CA2C22-DC03-4FF5-8350-59E32A3536BA}", "Machine")
[Environment]::SetEnvironmentVariable("CORECLR_PROFILER_PATH_32", "path\to\SL.DotNet.ProfilerLib.Windows_x86.dll", "Machine")
[Environment]::SetEnvironmentVariable("CORECLR_PROFILER_PATH_64", "path\to\SL.DotNet.ProfilerLib.Windows_x64.dll", "Machine")

[Environment]::SetEnvironmentVariable("SL_PROFILER_INITIALIZECOLLECTOR", "1", "Machine")
[Environment]::SetEnvironmentVariable('SL_BUILDSESSIONID', "$SL_BSID", "Machine")
#[Environment]::SetEnvironmentVariable('SL_BUILDSESSIONIDFILE', "path\to\buildSessionId.txt", "Machine")
[Environment]::SetEnvironmentVariable('SL_TOKENFILE', "path\to\sltoken.txt", "Machine")
[Environment]::SetEnvironmentVariable('SL_LABID', "$LAB_ID", "Machine")
#[Environment]::SetEnvironmentVariable("SL_PROFILER_INCLUDEPROCESSFILTER", "*include*,*what*,*is*,*ne?ded*", "Machine")

#Optional parameters
#[Environment]::SetEnvironmentVariable("SL_PROFILER_EXCLUDEPROCESSFILTER", "*exclude*,*unnee?ed", "Machine")
#[Environment]::SetEnvironmentVariable("SL_COVERAGECOLLECTOR_STARTUPINACTIVITYTIMEOUTSEC", "10", "Machine")
#[Environment]::SetEnvironmentVariable("SL_COVERAGECOLLECTOR_IDLETIMEOUTSEC", "0", "Machine")

export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER="{3B1DAA64-89D4-4999-ABF4-6A979B650B7D}"
export CORECLR_PROFILER_PATH_32="path\to\libSL.DotNet.ProfilerLib.Linux.so"
export CORECLR_PROFILER_PATH_64="path\to\libSL.DotNet.ProfilerLib.Linux.so"

export SL_PROFILER_INITIALIZECOLLECTOR=1
export SL_BUILDSESSIONID="$SL_BSID"
#export SL_BUILDSESSIONIDFILE="path\to\buildSessionId.txt"
export SL_TOKENFILE="path\to\sltoken.txt"
export SL_LABID="$LAB_ID"
#export SL_PROFILER_INCLUDEPROCESSFILTER="*include*,*what*,*is*,*ne?ded*"

#Optional parameters
#export SL_PROFILER_EXCLUDEPROCESSFILTER="*exclude*,*unnee?ed"
#export SL_COVERAGECOLLECTOR_STARTUPINACTIVITYTIMEOUTSEC=10
#export SL_COVERAGECOLLECTOR_IDLETIMEOUTSEC=0

If the process starts successfully, the profiler starts a connection to the collector using the same key. If the profiled process has child processes, they will reuse the same collector in most cases.

Ensure the variables specifying the profiler path are correct, given where you installed the agent binaries (for example: CORECLR_PROFILER_PATH_32=/usr/local/lib/libSL.DotNet.ProfilerLib.Linux.so)

When you successfully complete this step, you will see new entries appear in the Cockpit > Live Agents Monitor: the testListener and an entity called Profiler with the version details of your application.

Common Options

Logging (Optional)

To enable logging, you can add the following variable declaration.

[Environment]::SetEnvironmentVariable("SL_LOGGING_ENABLED", "true", "Machine")
[Environment]::SetEnvironmentVariable("SL_LOGLEVEL", "Debug", "Machine")
[Environment]::SetEnvironmentVariable("SL_LOGGING_TOFILE", "true", "Machine")
[Environment]::SetEnvironmentVariable("SL_LOGDIR", "path/to/logs/", "Machine")
[Environment]::SetEnvironmentVariable("SL_LOGGING_FILENAME", "path/to/logs/pic.log", "Machine")

Specific configurations

IIS/Windows

If your application is deployed on IIS, you'll need to follow the instructions below:

Don’t publish as a single-file/portable mode.

Define all env vars with absolute paths

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_TOKENFILE=C:\AbsolutePathToAgentFolder\sltoken.txt
SL_LABID=integ_main_TestAppWeatherApi
SL_BUILDSESSIONIDFILE=C:\AbsolutePathToFolder\buildSessionId.txt
SL_LOGLEVEL=Debug
SL_LOGGING_TOFILE=true
SL_LOGDIR=C:\AbsolutePathToLogsFolder\

Set the environment variables for 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 on the web application to wake it up.

Optimizing Collector Usage Across Multiple IIS Sites

If your IIS server serves multiple IIS sites on the same machine, by default each application pool starts its own profiler and Coverage Collector, which can increase resource usage. To reduce the number of active collectors, you can configure all profilers to connect to a single shared collector.

Add the following environment variables to your existing configuration:

SL_AGENT_PORT=31031
SL_COVERAGECOLLECTOR_STARTUPINACTIVITYTIMEOUTSEC=5

These settings ensure that all profilers share a single active collector bound to the specified port, while any unused collectors terminate quickly after a short inactivity period. This approach reduces system impact and optimizes resource usage.

Kubernetes / Containerized Deployment

If you can’t modify the image:

Mount a shared volume with the agent binaries.
Set env vars in the app container (see below).
Optionally use an initContainer to fetch the agent dynamically.

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:
      # Profiler - Generic vars
      - name: SL_TOKEN
          secretKeyRef:
          name: sealights
          key: SEALIGHTS_AGENT_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
	value: 1
      - name: SL_PROFILER_BLOCKING_CONNECTION_STARTUP
	value: "ASYNC"
      ### SL Profiler - Logging 
      - name: SL_LOGLEVEL
        value: "Debug"
      - name: SL_LOGGING_TOFILE
        value: "true"
      - name: SL_LOGDIR
        value: /sealights/logs/
      ### SL Profiler - Env Specific vars
      - name: SL_BUILDSESSIONIDFILE
        value: "path\to\buildSessionId.txt"
      - name: SL_LABID
        value: "integ_main_mysampleapplication"
    volumeMounts:
      - mountPath: /sealights
        name: sealights-dotnet-agent-file
  volumes:
    - name: sealights-dotnet-agent-file
      emptyDir: {}

PreviousCapturing coverage from the application NextMS Windows-specific Configurations

Last updated 21 days ago

Was this helpful?

Good morning

Why use the Profiler-Initiated Collector approach?

Agent Setup

Common Options

Logging (Optional)

Specific configurations

IIS/Windows

Optimizing Collector Usage Across Multiple IIS Sites

Kubernetes / Containerized Deployment