Skip to content
25 changes: 19 additions & 6 deletions docs/core/runtime-config/debugging-profiling.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ This article details the settings you can use to configure .NET debugging and pr

[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)]

> [!NOTE]
> Starting in .NET 11, profiler environment variables now support both `DOTNET` and `CORECLR` prefixes. The `DOTNET` prefix is the new standard, while `CORECLR` is maintained for backwards compatibility and might be removed in the future.

## Enable diagnostics

- Configures whether the debugger, the profiler, and EventPipe diagnostics are enabled or disabled.
Expand All @@ -23,11 +26,12 @@ This article details the settings you can use to configure .NET debugging and pr

- Configures whether profiling is enabled for the currently running process.
- If you omit this setting, profiling is disabled. This is equivalent to setting the value to `0`.
- To load a profiler, in addition to enabling profiling, the profiler GUID and profiler location also need to be configured using these settings.

| | Setting name | Values |
| - | - | - |
| **runtimeconfig.json** | N/A | N/A |
| **Environment variable** | `CORECLR_ENABLE_PROFILING` | `0` - disabled<br/>`1` - enabled |
| **Environment variable** | `CORECLR_ENABLE_PROFILING` or `DOTNET_ENABLE_PROFILING` | `0` - disabled<br/>`1` - enabled |

## Profiler GUID

Expand All @@ -36,19 +40,28 @@ This article details the settings you can use to configure .NET debugging and pr
| | Setting name | Values |
| - | - | - |
| **runtimeconfig.json** | N/A | N/A |
| **Environment variable** | `CORECLR_PROFILER` | *string-guid* |
| **Environment variable** | `CORECLR_PROFILER` or `DOTNET_PROFILER` | *string-guid* |

## Profiler location

Once profiling is enabled, the profiler can be loaded in two ways: with environment variables (cross-plat) or through the registry (Windows only). The profiler path environment variables take precedence over any COM library path in the registry if both are specified.

### Environment variable (cross-plat)

- Specifies the path to the profiler DLL to load into the currently running process (or 32-bit or 64-bit process).
- If more than one variable is set, the bitness-specific variables take precedence. They specify which bitness of profiler to load.
- For more information, see [Finding the profiler library](https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/profiling/Profiler%20Loading.md).

| | Setting name | Values |
| - | - | - |
| **Environment variable** | `CORECLR_PROFILER_PATH` | *string-path* |
| **Environment variable** | `CORECLR_PROFILER_PATH_32` | *string-path* |
| **Environment variable** | `CORECLR_PROFILER_PATH_64` | *string-path* |
| **Environment variable** | `CORECLR_PROFILER_PATH` or `DOTNET_PROFILER_PATH` | *string-path* |
| **Environment variable** | `CORECLR_PROFILER_PATH_32` or `DOTNET_PROFILER_PATH_32` | *string-path* |
| **Environment variable** | `CORECLR_PROFILER_PATH_64` or `DOTNET_PROFILER_PATH_64` | *string-path* |
| **Environment variable** | `CORECLR_PROFILER_PATH_ARM32` or `DOTNET_PROFILER_PATH_ARM32` | *string-path* |
| **Environment variable** | `CORECLR_PROFILER_PATH_ARM64` or `DOTNET_PROFILER_PATH_ARM64` | *string-path* |

### Through the registry (Windows only)

When the `DOTNET_PROFILER_PATH*` [environment variables](#environment-variable-cross-plat) aren't set while running on Windows, coreclr looks up the CLSID from `DOTNET_PROFILER` in the registry to find the full path to the profiler's DLL. Just like with any COM server DLL, the profiler's CLSID is looked up under HKEY_CLASSES_ROOT, which merges the classes from HKLM and HKCU.

## Export perf maps and jit dumps

Expand Down