dotnet/diagnostics: SOS, dotnet-dump and the .NET Core diagnostic CLI tools

What dotnet/diagnostics actually ships, and who it is for

The README describes the repository as the source code for various .NET Core runtime diagnostic tools. Five tools are listed with their own documentation pages: SOS, the debugger extension; dotnet-dump, a dump collection and analysis utility; dotnet-gcdump, which collects gcdumps of live .NET processes for heap analysis; dotnet-trace, which collects events from a running .NET Core application into a local trace file; and dotnet-counters, which monitors performance counters in real time. The repository also contains the managed portion of SOS and the lldb SOS plugin.

The audience is narrower than the tool list suggests. The stated goals are to build SOS and the lldb SOS plugin for the portable glibc platform (Centos 7) and for platforms the portable build does not support, named as Centos 6, Alpine and macOS, and to test across a matrix of distributions (Centos 6/7, Ubuntu, Alpine, Fedora, Debian, RHEL 7.2), architectures (x64, x86, arm, arm64), lldb versions (3.9 to 9.0) and .NET Core versions. A second goal is to make it easier to obtain a version of lldb, currently 3.9, on distributions that ship very old ones. A third is out-of-band development of SOS and lldb plugin features such as symbol server support for the .NET Core runtime.

If you are an application developer who wants to inspect a hung process, you are consuming the output of this repository, not its source. The distinction matters for every decision that follows.

The build matrix is the product: CMake, lldb versions and no cross-building

The build depends on Git, CMake, Python and a C++ compiler. Once those are installed, the README says the build is a matter of invoking the build script (build.cmd or build.sh) at the base of the repository. The repository layout matches that description: CMakeLists.txt, build.sh, Build.cmd, build.proj, build.sln, plus restore.sh, test.sh and dotnet.sh at the top level.

The constraint that shapes everything is stated plainly: there is no cross-building across OS, only for ARM, which is built on x64. You have to be on the particular platform to build that platform. That rules out the common pattern of producing Linux artifacts from a macOS laptop or a Windows CI runner without a matching agent. It also explains why the repository carries per-OS instruction pages for Windows, Linux, macOS, FreeBSD and NetBSD rather than one generic guide.

The lldb version range (3.9 to 9.0) is the other axis. Because the plugin is loaded into lldb, the version of lldb on the machine is part of the compatibility surface, and the README treats obtaining a suitable lldb on Centos, Alpine and Fedora as a goal in itself. If you are debugging on a distribution that ships a much newer lldb than 9.0, the README does not claim support for it.

Building the repository and where the tools come from

The repository is source, so the first step is cloning and building. The README gives the build as a single script invocation after Git, CMake, Python and a C++ compiler are present, and points to per-OS pages for installing those prerequisites. There is no cross-building across OS except ARM on x64, so run this on the platform you intend to debug.

git clone https://github.com/dotnet/diagnostics.git
cd diagnostics
./build.sh

Prerequisite installation differs by operating system, and the README does not inline it. Follow the page that matches your machine before running the build script:

# documentation/building/windows-instructions.md
# documentation/building/linux-instructions.md
# documentation/building/osx-instructions.md
# documentation/building/freebsd-instructions.md
# documentation/building/netbsd-instructions.md

For day-to-day use you generally do not build this repository at all. The tools are distributed through the GitHub Release tab, which the README points to for notes on SOS and diagnostic tools releases. The current release line is v10.0.731102, published on 2026-06-30, following v10.0.721401 on 2026-04-28 and v9.0.661903 on 2026-01-06. The README does not document rollback or downgrade steps, so pin the release you validated rather than tracking the newest one. For live processes, dotnet-counters monitors performance counters in real time and dotnet-gcdump collects a heap snapshot from a live process, which is the lighter option when you only need object graph data rather than a full dump.

Where the repository stops short

The README is a build and index document, not a user manual. It links out to documentation/sos.md, documentation/dotnet-dump-instructions.md, documentation/dotnet-gcdump-instructions.md, documentation/dotnet-trace-instructions.md and documentation/dotnet-counters-instructions.md, and it does not reproduce their contents. If you need command flags or output formats, the README is silent and you have to follow those pages.

The platform story is the real limitation. The portable build is glibc-based and the repository exists largely to cover what it does not: Centos 6, Alpine and macOS. If your target is a distribution outside the tested set, the matrix does not claim coverage, and the no-cross-building rule means you cannot work around that from a different host. FreeBSD and NetBSD have instruction pages, which suggests they are buildable, but the README does not list them in the test matrix.

The lldb range of 3.9 to 9.0 is a second boundary. Debugging against a newer lldb is outside what the README describes. And because the repository is the source for tools that also ship as releases, building main gives you something different from the released binaries; the README's release tab is the supported consumption path for the tools themselves.

How this differs from the dotnet/runtime debugging docs

The README links to Debugging CoreCLR in dotnet/runtime for instructions on debugging .NET Core and the CoreCLR runtime, and names dotnet/runtime as the source for the runtime. The split is deliberate and is one of the repository's stated goals: moving the managed portion of SOS (SOS.NETCore) here solves the source build problem of having it inside the runtime repository, and it allows out-of-band development of SOS and lldb plugin features such as symbol server support for the .NET Core runtime.

The practical difference is release cadence and scope. dotnet/runtime is the runtime; this repository is the diagnostic tooling around it, with its own release line (v10.0.731102, v10.0.721401, v9.0.661903) and its own build matrix. If you are debugging the runtime itself, the CoreCLR instructions are the relevant entry point. If you are debugging a managed process that runs on the runtime, the tools documented here are the ones you reach for. Choosing the wrong one wastes time on a build that produces artifacts you cannot use for your actual problem.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-06-30, the same date as the v10.0.731102 release. Releases are frequent enough to track .NET versioning: v10.0.731102 on 2026-06-30, v10.0.721401 on 2026-04-28, and v9.0.661903 on 2026-01-06. The version prefixes track .NET major versions, so a v10 release is the line that matches .NET 10.

Upgrade cost depends on which side you are on. Consuming released binaries means moving between release tags and re-reading the release notes on the GitHub Release tab, which the README directs you to. Building from source means re-running build.sh or build.cmd and re-validating against your lldb version, because the plugin loads into lldb and the README's supported range is 3.9 to 9.0. Neither path is documented as having a rollback procedure, so keep the previous release available.

The repository is licensed under the MIT license (LICENSE.TXT). The README states this directly. MIT is permissive and permits reuse and redistribution, but the repository also carries THIRD-PARTY-NOTICES.TXT, which means the full dependency set is not covered by a single licence statement. If you redistribute built artifacts, that file is the one to read. This is a description of what the repository contains, not legal advice.

Editorial conclusion

Adopt it if you debug .NET Core processes on Linux, macOS or Windows and need SOS, dotnet-dump, dotnet-gcdump, dotnet-trace or dotnet-counters, or if you are porting the lldb plugin to a distro the portable build does not cover. Do not adopt it if you want one binary to install: this is a source repository whose build depends on Git, CMake, Python and a C++ compiler, and the README states you must be on the target platform to build it. Before committing, read documentation/building/linux-instructions.md or osx-instructions.md for your platform, check the release notes on the GitHub Release tab for the tool you actually need, and confirm whether the musl-based platforms (Centos 6, Alpine, macOS) matter to you, because that is the case the repository was created to serve.

Frequently asked questions

Official sources

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