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:

Powershell

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

Linux

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.

Powershell

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

Linux

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: {}