Skip to content

.NET Tracer Manual

The tracer is a .NET profiler. It is loaded under certain conditions by the .NET runtime and generates traces containing calls to the crypto API (class, method, arguments, return value, stack trace).

Getting Started

The .NET runtime will pick up the profiler if it is provided with the right environment variables. The environment variables to set depend on whether your application runs on .NET Core or .NET Framework.

For .NET Core:

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

For .NET Framework:

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

You should additionally provide an output directory with:

CS_OUTPUT_DIR=C:\path\to\output

The directory should exist before the application is started.

Under those conditions, every time a .NET process is run, the tracer will output a .cst file and a .log file for that process. The CST file can be uploaded to the Analyzer while the log file is mostly useful for debugging.

Setting environment variables

There are several ways to set the required environment variables, each with their pros and cons.

PowerShell

In PowerShell, you can set temporary environment variables that will only affect the current PowerShell session:

$env:COR_ENABLE_PROFILING = 1
$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:CS_OUTPUT_DIR = 'C:\output'
...
/path/to/application.exe

The advantage is that you ensure that you'll only be tracing the expected application, not other applications. A potential disadvantage is that you might not be able to start all applications or components that way.

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. However, if any other component is launched while the environment variables are set, they will be traced as well.

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.