Skip to content

.NET Tracer Reference Manual

Installation

Before you can use the .NET Tracer, see installation instructions.

Configuration

Runtime configuration

For the .NET tracer profile to work, it must be loaded by the .NET runtime used by your application. This is done differently for .NET Framework and .NET Core.

For ease of use, you may want to set some of those variables at the system level (e.g. in "System Properties", "Advanced", "Environment Variables..."). However, if you do not want to trace all .NET applications on your machine, we recommend to avoid setting CORECLR_ENABLE_PROFILING or COR_ENABLE_PROFILING globally. Go to "Getting Started" page to see how that can be done.

.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 itself can be configured with the following environment variables:

  • CS_OUTPUT_DIR: Path to a directory where trace and log files will be written to (default is the current directory). Make sure the application under test has the right to create files in this directory.

Setting environment variables in Windows

There are several ways to set the required environment variables, each with their pros and cons, which can be mixed together.

System environment variables

By setting the variables at the system level (e.g. in "System Properties", "Advanced", "Environment Variables..."), you will be able to ensure that all components of your applications are traced, even if several processes are created.

The main caveat of this method is that setting CORECLR_ENABLE_PROFILING or COR_ENABLE_PROFILING to 1 at the system level may result in unexpected applications being traced, including Windows services, which could cause confusion.

Therefore, you may want to only set COR_PROFILER_*, CORECLR_PROFILER_* variables at the system level, and set COR_ENABLE_PROFILING to 1 using one of the other methods outlined below.

PowerShell

In PowerShell, you can set temporary environment variables that will only affect the current PowerShell session (example for a .NET Framework application):

$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

An advantage of this method is that it ensures that you will only be tracing the expected application, not other applications. However, you might not be able to start all applications or components that way. For example, some applications rely on a launcher process which will not forward the environment variables to the actual application process.

Launch Profile with the dotnet CLI or Visual Studio

If your application is launched from the dotnet CLI or Visual Studio, you can also set the environment variables by using a launch profile.

Unit tests

To trace unit tests, you will probably need a data collector. Follow instructions on https://github.com/cryptosense/dotnet-collector.

If you run your tests with the Cake build system, it is possible to configure the environment variables in build.cake.

In some cases, the tracer interferes with other profilers, so it is important to ensure those are disabled while the tracer is used. For instance, this is the case of OpenCover, a code coverage tool for .NET tests.