Skip to content

.NET Tracer reference🔗

Configuration🔗

Runtime configuration🔗

The .NET tracer profile must be loaded by the .NET runtime used by your application in order to function. This process differs between .NET Framework and .NET Core.

For convenience, consider setting some of these variables at the system level (e.g. in System Properties, Advanced, Environment Variables, etc.). However, if you’d prefer not to trace all .NET applications on your machine, it’s best to refrain from globally configuring CORECLR_ENABLE_PROFILING or COR_ENABLE_PROFILING.

Visit Getting Started for more information.

.NET Core (Linux 64-bit only)🔗

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-9ccb4916d2e5}
CORECLR_PROFILER_PATH_64=/path/to/cs_dotnet_tracer_64.so

.NET Core (Windows)🔗

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-9ccb4916d2e5}
CORECLR_PROFILER_PATH_32=C:\path\to\cs_dotnet_tracer_32.dll
CORECLR_PROFILER_PATH_64=C:\path\to\cs_dotnet_tracer_64.dll

.NET Framework (Windows)🔗

COR_ENABLE_PROFILING=1
COR_PROFILER={cf0d821e-299b-5307-a3d8-9ccb4916d2e5}
COR_PROFILER_PATH_32=C:\path\to\cs_dotnet_tracer_32.dll
COR_PROFILER_PATH_64=C:\path\to\cs_dotnet_tracer_64.dll

Tracer configuration🔗

The .NET tracer can be configured with the following environment variables:

  • CS_OUTPUT_DIR: Directory path where trace and log files will be written (the default is the current directory). Make sure the application has write permissions in this directory.

Setting environment variables in Windows🔗

There are several ways to set the required environment variables. Each method has pros and cons and can be used in combination.

System environment variables🔗

Setting the variables at the system level (e.g. in System Properties, Advanced, Environment Variables, etc.), ensures comprehensive tracing across all application components, even if several processes are created.

A key concern with this method is that configuring CORECLR_ENABLE_PROFILING or COR_ENABLE_PROFILING to 1 at the system level may trace unintended applications, including Windows services, leading to potential confusion.

Because of this, you may prefer to only set the COR_PROFILER_* and CORECLR_PROFILER_* variables at the system level, and set COR_ENABLE_PROFILING to 1 using alternative methods described below.

PowerShell🔗

You can set temporary environment variables that will only affect your current PowerShell session. An example for a .NET Framework application is:

PowerShell
$env:COR_PROFILER = '{cf0d821e-299b-5307-a3d8-9ccb4916d2e5}'
$env:COR_PROFILER_PATH_32 = 'C:\path\to\cs_dotnet_tracer_32.dll'
$env:COR_PROFILER_PATH_64 = 'C:\path\to\cs_dotnet_tracer_64.dll'
$env:COR_ENABLE_PROFILING = 1
$env:CS_OUTPUT_DIR = 'C:\path\to\output\dir'
...
/path/to/application.exe

This approach has the benefit of exclusively tracing the intended application, while omitting others. However, some applications or components may not initiate using this method. For instance, some applications rely on a launcher process that doesn’t pass environment variables to the actual application process.

Launch Profile with the dotnet CLI or Visual Studio🔗

When launching your application from the dotnet CLI or Visual Studio, environment variables can also be configured using a launch profile.

Unit tests🔗

You’ll likely require a data collector to trace unit tests. Detailed instructions are available on GitHub.

If you execute tests using the Cake build system, it’s possible to configure the environment variables in build.cake.

The tracer may sometimes conflict with other profilers, so it’s crucial to disable these while running the trace. One known instance is OpenCover, a code coverage tool for .NET tests.

Troubleshooting🔗

If the .NET Tracer isn’t working as expected, try following the troubleshooting steps.

Event Viewer logs🔗

Check Windows Event Viewer for any related error logs.

To do this:

  1. Press the Windows and R keys at the same time on your keyboard.
  2. Type eventvwr.msc.
  3. Press the Enter key.

Review the Application logs for any recent errors that might be related to the tracer.

Previous versions of VC Redistributable🔗

Make sure that there aren’t any other versions of the Visual C++ Redistributable installed that may conflict with the current version.

Error Messages🔗

If any error messages appear while trying to run the tracer, make note of the exact text or take a screenshot and submit it to our portal.

Antivirus Interference🔗

Make sure to temporarily disable any antivirus software to rule out interference. This can typically be done by right-clicking the antivirus icon in the system tray (bottom-right corner of the screen) and selecting the disable option. Remember to re-enable it after testing.

Permission issues🔗

Make sure you can use the tracer with administrative rights:

  1. Right-click on the tracer and select Properties.
  2. Navigate to the Compatibility tab and select Run this program as an administrator.
  3. Select OK.