ProcDump for Linux: trigger-based core dumps from the command line

The problem ProcDump for Linux solves

A core dump is most useful when it is taken while the process is misbehaving. Waiting for a crash, or attaching a debugger after the fact, often means the interesting state is gone. ProcDump for Linux exists to make the dump conditional: you describe the condition, and the tool writes the dump when that condition is met. The README describes it as a Linux and macOS reimagining of the Sysinternals ProcDump tool, which creates process dumps in response to performance, runtime, signal, and resource-tracking triggers.

The audience is narrower than the name suggests. This is a command-line tool for engineers debugging native Linux processes and .NET applications on Linux, plus macOS users who accept the reduced trigger set the README mentions for the Mac version. It is not a profiler and it does not analyse the dump. It gets the file onto disk at the right moment, and the rest of the work happens in gdb or another debugger.

One design decision is worth flagging early. With ProcDump 1.3 the README announces a breaking change: the switches are now aligned with the Windows ProcDump version. Anyone carrying scripts written against older releases should expect to rewrite the flags rather than assume the old ones still resolve.

How the triggers and the dump path actually work

The repository is a Cargo workspace with four members: crates/procdump, crates/procdump-capi, crates/procdump-cli and xtask. The README states that Linux and macOS process access sit behind shared Rust interfaces, and that the Cargo workspace is the supported implementation. The procdump crate holds the safe Rust API and the shared dump and monitoring implementation, while procdump-cli is the command-line application and procdump-capi exposes a static C ABI with a public header.

Dump writing depends on the target. Linux native dumps use the Rust corex ELF writer by default. Managed dumps go through .NET diagnostics IPC. macOS and the explicit Linux -usegcore fallback use gcore. That fallback switch is the honest part of the design: the default path is a Rust ELF writer, but the tool still depends on gcore being available, and the requirements list gdb and gcore for both Linux and macOS.

Two native components sit under crates/procdump/native/: an optional Linux eBPF kernel program and an optional injected CLR profiler, both built and embedded by Cargo. Their userspace loading, monitoring, EventPipe handling, orchestration, reporting and dump writing are Rust. The feature model follows the same split. The procdump crate's default feature set supports immediate dump generation, while monitoring, .NET triggers and restrack are additive features, and the CLI enables full. So a library consumer can build a small binary that only takes an immediate dump, without pulling in the monitoring machinery.

Installing ProcDump for Linux and taking a first dump

The README does not inline installation steps. It says to see the installation instructions in INSTALL.md and the build instructions in BUILD.md, so those two files are where the actual commands live. What the README does give is the dependency list and the workspace build commands.

On Linux you need Rust stable with rustfmt and clippy, Clang, pkg-config, the libelf and zlib development packages, gdb and gcore. The .NET SDK or runtime is only needed for managed integration scenarios. With those present, the workspace builds and tests with:

cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

The clippy invocation treats warnings as errors, which tells you the project expects a clean lint run rather than a best-effort one. The workspace pins rust-version = "1.85" and edition 2024 in Cargo.toml, so an older toolchain will fail before it compiles anything.

Once built, the simplest real use is an immediate dump of a running process. The README's examples all target a process with pid 1234:

sudo procdump 1234

That writes a core dump straight away. The more representative use is a trigger. This example creates a dump each time the process has CPU usage at or above 65 percent, up to three times, with at least ten seconds between dumps:

sudo procdump -c 65 -n 3 1234

-n sets the number of dumps to write before exiting, and -s sets the consecutive seconds before a dump is written, defaulting to 10. If the process is not running yet, -w makes the tool wait for it to launch. Expect the command to sit in the foreground until the trigger fires or the dump count is reached, and expect to need sudo, since the examples all use it.

Resource tracking and the .NET triggers

The -restrack switch is the part of ProcDump for Linux that has no Windows equivalent worth comparing. The README says it activates resource tracking and reports resource allocations that have not been freed at the time of dump generation, saved to a file with a .restrack extension. The tracked allocation functions are malloc, calloc, realloc, reallocarray and mmap; the deallocation side covers free and munmap. That is a leak report attached to a dump, not a heap profiler.

-restrack can run alone, in which case the README says to use 't' to manually capture a restrack report, or alongside other triggers with the nodump option to produce reports without dumps. The -sr switch sets the sample rate for this tracking, and -fx filters on the content of restrack call stacks with wildcard support. The Mac version does not implement resource tracking at all, so this is a Linux-only capability.

The .NET side is a separate set of triggers: -gcm for GC memory thresholds by generation or heap, -gcgen to dump when a garbage collection of a given generation starts and finishes, -pc and -pcl for performance counters with optional percentile selection such as [p50], [p95] or [p99], and -e to dump when the process encounters an exception, with -f and -fx filtering the exception content. These depend on the injected CLR profiler and the .NET diagnostics IPC path, which is why the README lists the .NET SDK or runtime as a requirement only for managed integration scenarios.

Where ProcDump for Linux is the wrong tool

The tool assumes a working dump path on the host. The requirements list gdb and gcore for both Linux and macOS, and the README states that macOS and the explicit Linux -usegcore fallback use gcore. If gcore is missing, or if the environment restricts ptrace, the trigger logic can still fire while the dump itself fails. The README does not document rollback or recovery for a failed dump write, and it does not describe what happens to the trigger counter when a write fails. That is a gap worth knowing about before you rely on it unattended.

Second, the trigger set is not uniform across platforms. The README is explicit that the Mac version currently has a limited set of triggers, and that resource tracking is not implemented there. Treating the two platforms as interchangeable will not work.

Third, this is not a replacement for a debugger or a profiler. It produces a core file or a restrack report. Reading either one is still your problem. If what you actually want is a stack sample or a flame graph under load, a sampling profiler is the right category, and ProcDump will only give you a large binary file. If you want a single core dump of a hung process with no condition attached, plain gcore is simpler and has fewer dependencies. And the -mc switch, which sets a custom core dump mask in hex, means the size of what you collect is under your control: a permissive mask can produce very large files, and the README points to man core and /proc/[pid]/coredump_filter rather than explaining the trade-offs itself.

gcore and the corex ELF writer: what actually differs

The obvious alternative is gcore, which ships with gdb and appears in this project's own requirements list. The difference is not in the dump format but in when the dump happens. gcore is imperative: you run it against a pid and it writes a core file now. ProcDump for Linux is conditional: you declare a threshold, a signal set, a thread or file descriptor count, or a .NET event, and the dump is written when that condition is met, with -n controlling how many times and -s controlling the spacing. That is the whole reason to add a dependency instead of calling gcore directly.

A second difference is the writer. Linux native dumps use the Rust corex ELF writer by default rather than gcore, and -usegcore exists as an explicit fallback. So the tool is not simply a wrapper around gdb. If you have an existing pipeline that expects gcore's output, the fallback switch is the compatibility path, and it is worth testing both before committing.

A third difference is scope. gcore knows nothing about malloc, calloc, realloc, reallocarray, mmap, free or munmap, and nothing about .NET garbage collection or performance counters. ProcDump for Linux covers those through -restrack, -gcm, -gcgen, -pc and -pcl. If your problem is a leak or a managed runtime stall, gcore alone will not produce the report you need.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-14. The most recent release listed is 3.5.3, published on 2026-09-10, following 3.5.2 on 2026-06-16 and 3.5.1 on 2026-05-07. That cadence of roughly monthly to quarterly releases suggests the project is being worked on, though the README's own warning about the ProcDump 1.3 switch realignment is the reminder that releases here can break command lines.

The licence is MIT, declared in both the repository metadata and the workspace package section of Cargo.toml. MIT is permissive: it allows use in closed-source products provided the copyright notice and permission notice are retained. There is also a NOTICE.txt at the top level, which is where attribution details would live. This is a description of the licence text, not legal advice; if the dump files or the injected CLR profiler touch code you redistribute, have your own counsel look at the NOTICE file.

The upgrade cost has three parts. The Rust toolchain floor is rust-version = "1.85" with edition 2024, so a pinned older toolchain blocks the build. The workspace denies unsafe_code in [workspace.lints.rust], which is a constraint for anyone consuming the procdump crate and adding their own code. And the release profile sets lto = "thin", codegen-units = 1 and strip = "symbols", so release binaries are stripped, which matters if you were hoping to debug the tool itself rather than the target process.

Editorial conclusion

ProcDump for Linux suits engineers who need a dump captured at the moment a condition occurs, not after the fact, and who are comfortable building a Rust workspace with Clang, pkg-config, libelf and zlib development packages, gdb and gcore present. It is the wrong tool if you only need a one-off core file, because gcore already does that, and if you cannot install those build dependencies or run the tool with sudo. Before relying on it, verify the installation steps in INSTALL.md against your distribution, confirm that gcore is on PATH on your machine, and decide whether the default Rust corex ELF writer or the -usegcore fallback produces dumps your debugger reads correctly.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/ProcDump-for-Linux on GitHub
4. README
5. Releases