dotnet/diagnostics: The source repo behind SOS and the .NET diagnostic CLI tools

What this repository actually contains

The README states that dotnet/diagnostics is the source for several .NET Core runtime diagnostic tools. The main component is SOS, the debugger extension, including its managed portion and the lldb plugin. Alongside SOS, the repo holds the source for four global diagnostic tools: dotnet-dump, dotnet-gcdump, dotnet-trace, and dotnet-counters. These are the same tools that a .NET developer would install as global tools, but here they are built from source. The repository also exists to make it easier to obtain a version of lldb (currently 3.9) with scripts and documentation for platforms that ship older versions. If you are an engineer who needs to debug a .NET Core process on a nonstandard Linux distro, this is where the tooling starts.

Why the repository exists: out-of-band SOS development

The README gives two explicit goals. First, to build SOS and the lldb plugin for the portable glibc-based Linux platform (CentOS 7) and for platforms the portable build does not support, such as musl-based builds, CentOS 6, Alpine, and macOS. Second, to support out-of-band development of new SOS and lldb plugin features, like symbol server support for the .NET Core runtime. The repository also solves the source build problem of having SOS.NETCore, the managed portion of SOS, inside the runtime repo. That separation matters: it lets SOS evolve independently of the runtime, which is a real architectural decision. For an adopter, this means the diagnostic tools can receive updates without waiting for a runtime release, but it also means you need to track two repositories to understand the full debugging stack.

The build process and its constraints

Building the repository is straightforward in principle. The README says you need Git, CMake, Python, and a C++ compiler. Once those are installed, you invoke the build script at the base of the repository: build.cmd on Windows or build.sh on Unix. There is no cross-building across operating systems, with one exception: ARM builds are done on x64. That means if you want a build for Alpine, you must build on Alpine. The README points to OS-specific instructions for Windows, Linux, macOS, FreeBSD, and NetBSD. The test matrix is large: OSes include CentOS 6/7, Ubuntu, Alpine, Fedora, Debian, and RHEL 7.2, and architectures include x64, x86, arm, and arm64. The lldb versions tested range from 3.9 to 9.0. If your target platform is not in that list, you are on your own, and the build may fail in ways that are not documented.

The diagnostic tools: what each one does

The README lists four global diagnostic tools with one-line descriptions. dotnet-dump collects and analyzes dumps. dotnet-gcdump collects gcdumps of live .NET processes for heap analysis. dotnet-trace enables the collection of events for a running .NET Core application to a local trace file. dotnet-counters monitors performance counters of a .NET Core application in real time. These are the tools a support engineer would reach for when a production process is misbehaving. The descriptions are brief, so the README does not tell you the exact command syntax. For that, you need the linked documentation files, such as documentation/dotnet-dump-instructions.md. The repository is the source, not the user guide. If you are evaluating the tools themselves, you may want to install the released global tools rather than build from source.

Licensing and maintenance cost

The repository is licensed under the MIT license, which is permissive. The README states this explicitly. There is no copyleft obligation, so you can use the source in proprietary projects, though you should check the license file for exact terms. Maintenance cost is tied to the release cadence. Recent releases are versioned like v10.0.731102 and v9.0.661903, with dates in 2026. The last push was 2026-06-30, suggesting active development. Because the build matrix spans many OS and lldb versions, maintaining a custom build means you must track upstream changes. The README notes that the repository is not archived and the default branch is main, so expect ongoing changes. If you fork, you will need to rebase frequently to keep up with the test matrix updates.

Limitations and when it is the wrong tool

The most obvious limitation is the build platform requirement. You cannot build for a target OS from a different OS, except ARM from x64. That means a CI pipeline for multiple platforms needs multiple build agents. The README also mentions lldb version 3.9 as the current version the repo helps obtain, which is old. If your debugger workflow depends on a newer lldb, you may need to adjust. Another limitation is that the README is thin on usage details for the tools. It points to documentation files, but those are not included in the README excerpt. If you need to know the exact flags for dotnet-trace, you must read the linked instructions. The repository is also not a replacement for the runtime source. It contains diagnostic tools, not the CoreCLR runtime. If your goal is to debug the runtime internals, you need dotnet/runtime as well. The README links to it, but the diagnostics repo alone will not give you the runtime source.

Alternatives: what else exists for .NET diagnostics

The primary alternative is to use the prebuilt diagnostic tools that ship with the .NET SDK. The dotnet-dump, dotnet-gcdump, dotnet-trace, and dotnet-counters tools are available as global tools, so you can install them with dotnet tool install without building anything. That approach is simpler and gives you the same functionality, but you do not get the ability to modify SOS or the lldb plugin. Another alternative is to use the runtime's built-in diagnostics, such as EventPipe, which dotnet-trace wraps. The README does not describe EventPipe, but the existence of dotnet-trace implies a lower-level event collection mechanism. For debugging native code, you could use lldb directly with your own scripts, but you would lose the SOS managed debugging features. The difference in approach is that dotnet/diagnostics gives you source-level control and the ability to build for unsupported platforms, while the global tools give you convenience and official support.

Editorial conclusion

Adopt dotnet/diagnostics if you need to build SOS or the lldb plugin from source for a Linux distribution not covered by the portable build, or if you want to contribute to the diagnostic tools that ship with .NET. Do not adopt it if you only need the ready-made tools: install the dotnet-* global tools from the .NET SDK instead. Before building, verify your platform is in the supported list (CentOS 6/7, Ubuntu, Alpine, Fedora, Debian, RHEL 7.2, plus macOS and the BSDs) and check the relevant OS-specific instructions in documentation/building. The repository requires Git, CMake, Python, and a C++ compiler, and there is no cross-building except for ARM from x64. The MIT license imposes few restrictions, but the build matrix is large and the release cadence is tied to .NET versions, so expect to re-run builds when you update the runtime.

Official sources

1. Official README
2. Project repository
3. Release notes