Configuring the Profiler-Initiated Collector

Why use the Profiler-Initiated Collector (PIC) approach?

The PIC approach simplifies .NET application instrumentation by leveraging built-in .NET / .NET Core profiling. It lets the profiler start the collector automatically as a detached process, with settings provided via environment variables or a configuration file, and stops the collector when the profiled process ends.

In some environments, there is no straightforward place to start the Coverage Collector explicitly:

Docker – modifying the entry point or command script can be complex.
Azure / Azure DevOps – no way to start the collector before IIS or override the test runner.
PCF – background tasks complicate executing commands to stop the collector (aka BGTL).

To enable this feature, set the environment variable SL_PROFILER_INITIALIZECOLLECTOR=1 to instruct the SeaLights Profiler to initialize its collector.

Best Practice: For containerized environments where you prefer not to modify the image, mount a folder containing the SeaLights Agent and point the profiler to it via the mounted path.

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)

Logging helps diagnose issues related to the profiler or collector startup, configuration, and connectivity. You can enable and fine-tune logging by setting the following environment variables:

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

For advanced logging capabilities — such as controlling verbosity levels, enabling performance monitoring, or limiting logs to the Collector only — refer to the Agent Logging Configuration section of the documentation.

Specific configurations

IIS/Windows

If your application is deployed on IIS, follow the steps below:

Don’t publish the application in single-file or portable mode.

Define the Environment Variables

Define all necessary environment variables using 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\

Optimizing Collector Usage Across Multiple IIS Sites

If your IIS server hosts multiple sites on the same machine, each application pool will, by default, start its own profiler and Coverage Collector. This can increase resource usage.

To reduce the number of active collectors, configure all profilers to connect to a single shared collector by adding 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 collector instance bound to the specified port, while unused collectors terminate quickly after a short inactivity period. This approach reduces system overhead and optimizes resource usage.

Set the Variables in the Windows Registry

You can update the IIS environment variables in the Windows Registry using either a manual approach or PowerShell commands; both methods achieve the same result.

Set the environment variables for the IIS services in the Windows Registry:

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 named Environment

To remove the environment variables manually, simply delete the Environment value from both registry keys.

You can store your environment variable configuration in a text file (for example, SL-IIS-Envvars.txt) and use the following command to add it to the Registry:

"WAS","W3SVC" | ForEach-Object { Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\$_" -Name "Environment" -Value (Get-Content 'C:\AbsolutePathToFolder\SL-IIS-Envvars.txt') -Type MultiString }

To remove the configuration, run the following command:

"WAS","W3SVC" | ForEach-Object { Remove-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\$_" -Name "Environment" }

Restart the IIS Server to apply the changes

Restart the IIS Server using iisreset /restart
Access your web application once to wake it up and verify that profiling starts correctly.

When this step is complete, new entries will appear in Cockpit > Live Agents Monitor: the testListener and an entity named Profiler, showing the version details of your application and the IIS AppPool it is attached to in the Tag column

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 2 months ago

Was this helpful?

Good morning

hashtagWhy use the Profiler-Initiated Collector (PIC) approach?

hashtagAgent Setup

hashtagCommon Options

hashtagLogging (Optional)

hashtagSpecific configurations

hashtagIIS/Windows

hashtagDefine the Environment Variables

hashtagOptimizing Collector Usage Across Multiple IIS Sites

hashtagSet the Variables in the Windows Registry

hashtagRestart the IIS Server to apply the changes

hashtagKubernetes / Containerized Deployment

Why use the Profiler-Initiated Collector (PIC) approach?

Agent Setup

Common Options

Logging (Optional)

Specific configurations

IIS/Windows

Define the Environment Variables

Optimizing Collector Usage Across Multiple IIS Sites

Set the Variables in the Windows Registry

Restart the IIS Server to apply the changes

Kubernetes / Containerized Deployment