Creating memory dumps using Sysinternals ProcDump for Mac

The Sysinternals ProcDump tool has long been a go-to utility for capturing process memory dumps, especially for diagnosing performance issues like excessive CPU or memory usage. Its key strength lies in its ability to monitor specific conditions and automatically generate dumps when thresholds are breached — ideal for intermittent issues that are hard to replicate.

Previously available on Windows and Linux, ProcDump has now been extended to macOS. With the release of ProcDump 1.0 for Mac, users can enjoy consistent functionality across all three major platforms — Windows, Linux, and macOS. This makes ProcDump a versatile choice for developers and system administrators dealing with cross-platform diagnostics and performance tuning.

A note on security

A memory dump is a detailed snapshot of a process’s memory at a given moment in time. Because it captures the full contents of memory, it may contain highly sensitive information such as passwords, personal identifiers, encryption keys, and other critical data.

To safeguard this information consider using proper access controls, secure storage, limited permissions and retention policies.

Maintaining the confidentiality and integrity of memory dumps is vital to prevent potential data breaches or misuse.

Installing ProcDump on Mac

ProcDump for Mac is now easily installable via Homebrew, the popular package manager for macOS.

Install Homebrew: If you don’t have Homebrew installed, visit brew.sh for step-by-step instructions.

Add the Sysinternals Tap: Once Homebrew is installed, add the Sysinternals tap to access ProcDump and other Sysinternals tools. Run the following command in your terminal:

brew tap Microsoft/sysinternalstap

Install ProcDump: With the tap added, install ProcDump for Mac using:

brew install procdump

Running ProcDump on Mac

Since ProcDump generates a memory dump which contains the memory contents of the target process, we have to run it using sudo.

% sudo procdump
ProcDump v1.0.0 - Sysinternals process dump utility
Copyright (C) 2024 Microsoft Corporation. All rights reserved. Licensed under the MIT license.
Mark Russinovich, Mario Hewardt, John Salem, Javid Habibi
Sysinternals - www.sysinternals.com
Monitors one or more processes and writes a core dump file when the processes exceeds the
specified criteria.

Capture Usage: 
   procdump [-n Count]
            [-s Seconds]
            [-c|-cl CPU_Usage]
            [-m|-ml Commit_Usage1[,Commit_Usage2...]]
            [-tc Thread_Threshold]
            [-fc FileDescriptor_Threshold]
            [-pf Polling_Frequency]
            [-o]
            [-log syslog|stdout]
            {
             {{[-w] Process_Name | PID} [Dump_File | Dump_Folder]}
            }
Options:
   -n      Number of dumps to write before exiting.
   -s      Consecutive seconds before dump is written (default is 10).
   -c      CPU threshold above which to create a dump of the process.
   -cl     CPU threshold below which to create a dump of the process.
   -tc     Thread count threshold above which to create a dump of the process.
   -fc     File descriptor count threshold above which to create a dump of the process.
   -pf     Polling frequency.
   -o      Overwrite existing dump file.
   -log    Writes extended ProcDump tracing to the specified output stream (syslog or stdout).
   -w      Wait for the specified process to launch if it's not running

Based on the available triggers, let’s say we wanted to generate a core dump when the CPU consumption of a target process with identifier 9036 is above 90%:

% sudo procdump -c 90 9036  

ProcDump v1.0.0 - Sysinternals process dump utility
Copyright (C) 2024 Microsoft Corporation. All rights reserved. Licensed under the MIT license.
Mark Russinovich, Mario Hewardt, John Salem, Javid Habibi
Sysinternals - www.sysinternals.com

Monitors one or more processes and writes a core dump file when the processes exceeds the
specified criteria.

[15:27:56 - INFO]: Press Ctrl-C to end monitoring without terminating the process(es).
Process:                                top (9036)
CPU Threshold:                          >= 90%
Commit Threshold:                       n/a
Thread Threshold:                       n/a
File Descriptor Threshold:              n/a
Polling Interval (ms):                  1000
Threshold (s):                          10
Number of Dumps:                        1
Output directory:                       .
[15:27:56 - INFO]: Starting monitor for process top (9036)
[15:27:57 - INFO]: Trigger: CPU usage:95% on process ID: 9036
[15:28:07 - INFO]: Core dump 0 generated: ./top_cpu_2024-11-15_15:27:57.9036
[15:28:07 - INFO]: Stopping monitor for process top(9036)

In the example above, ProcDump is configured to monitor until the process exceeds 90% CPU usage. Upon detecting a spike (e.g., at 95%), ProcDump automatically generates a memory dump for analysis.

This is just one example of a trigger (CPU) that ProcDump supports but there are others as well (memory, thread count, file descriptor count). Please note that the first version of ProcDump for Mac does not have full trigger parity, but we are actively working on adding the others as well.

We would love your feedback!

ProcDump’s automated memory dump generation is super powerful. By capturing the memory dump at the moment an issue occurs, ProcDump simplifies root cause analysis, ensuring that transient issues don’t go unnoticed. It’s a great tool for performance troubleshooting and debugging.

We are always looking at adding support for new events and would love to hear from you if there are new events you would be interested in and/or any feedback in general.

You can find us on GitHub here.