Skip to content

[Diagnostics] Update dotnet-trace collect-linux and perfmap enablement #54354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mdh1418 wants to merge 4 commits into
base: main
Choose a base branch
from
+6 −4
Open

[Diagnostics] Update dotnet-trace collect-linux and perfmap enablement #54354

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
efe29fc
[Dotnet-Trace] Update glibc compatibility note
mdh1418 Mar 19, 2026
398bd83
[Diagnostics] Update PerfMap enable options
mdh1418 Jun 11, 2026
6beb368
update date
mdh1418 Jun 11, 2026
49724d2
Elaborate diagnostics IPC command options in table
mdh1418 Jun 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/core/diagnostics/dotnet-trace.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: dotnet-trace diagnostic tool - .NET CLI
description: Learn how to install and use the dotnet-trace CLI tool to collect .NET traces of a running process without the native profiler, by using the .NET EventPipe.
ms.date: 03/19/2026
ms.date: 06/10/2026
ms.topic: reference
ms.custom: sfi-ropc-nochange
---
Expand Down Expand Up @@ -311,8 +311,8 @@ Collects diagnostic traces using perf_events, a Linux OS technology. `collect-li
- .NET 10+

> [!NOTE]
> The `collect-linux` verb only runs on Linux x64 and Linux Arm64 environments that have glibc version 2.35 or later.
> All of the [.NET 10 officially supported Linux distros](https://github.com/dotnet/core/blob/main/release-notes/10.0/supported-os.md#linux) support this requirement except Alpine 3.22, CentOS Stream 9, and any distros based off Red Hat Enterprise Linux 9.
> The `collect-linux` verb only runs on Linux x64 and Linux Arm64 environments that have glibc version 2.27 or later.
> All of the [.NET 10 officially supported Linux distros](https://github.com/dotnet/core/blob/main/release-notes/10.0/supported-os.md#linux) support this requirement except Alpine 3.22.
> A quick way to check the version of a system's libc is with the command `ldd --version` or by executing the libc library directly.

> [!TIP]
Expand Down
4 changes: 3 additions & 1 deletion docs/core/runtime-config/debugging-profiling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Debugging profiling config settings
description: Learn about runtime settings that configure debugging and profiling for .NET apps.
ms.date: 11/27/2019
ms.date: 06/10/2026
---
# Runtime configuration options for debugging and profiling

Expand Down Expand Up @@ -65,6 +65,7 @@ When the `DOTNET_PROFILER_PATH*` [environment variables](#environment-variable-c

- Enables or disables perf maps or jit dumps. These files allow third party tools, such as the Linux `perf` tool, to provide human readable names for dynamically generated code and precompiled ReadyToRun (R2R) modules.
- If you omit this setting, writing perf map and jit dump files are both disabled. This is equivalent to setting the value to `0`.
- On .NET 8 and later, the runtime can enable and disable perf maps and jit dump files on demand in response to a diagnostic IPC request. See [EnablePerfMap](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md#enableperfmap), [DisablePerfMap](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md#disableperfmap), and [DiagnosticsClient APIs](../diagnostics/microsoft-diagnostics-netcore-client.md#perfmap-methods).
- When perf maps are disabled, not all managed callsites will be properly resolved.
- Depending on the Linux kernel version, both formats are supported by the `perf` tool.
- Enabling perf maps or jit dumps might cause up to a 20% overhead, though often it's much less. To minimize performance impact, it's recommended to selectively enable either perf maps or jit dumps, but not both. The impact only occurs while the application is JITing code. Often that occurs at startup, but it might occur later if the application is running a new code path for the first time.
Expand All @@ -80,6 +81,7 @@ The following table compares perf maps and jit maps.
|------------------------|--------------|--------|
| **runtimeconfig.json** | N/A | N/A |
| **Environment variable** | `DOTNET_PerfMapEnabled` | `0` - disabled<br/>`1` - perf maps and jit dumps both enabled<br/>`2` - jit dumps enabled<br/>`3` - perf maps enabled |
| [**Diagnostics IPC Command**](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md) | `EnablePerfMap`, `DisablePerfMap` | `EnablePerfMap(PerfMapType.All)` - perf maps and jit dumps<br/>`EnablePerfMap(PerfMapType.JitDump)` - jit dumps only<br/>`EnablePerfMap(PerfMapType.PerfMap)` - perf maps only<br/>`DisablePerfMap()` - disabled |

For EventPipe-related environment variables, see [Trace using environment variables](../diagnostics/eventpipe.md#trace-using-environment-variables).

Expand Down
Loading