├── LICENSE
└── README.md


/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2024 Sysinternals
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # ProcDump 
 2 | ProcDump for Mac provides a convenient way for Mac developers to create core dumps of their application based on performance triggers. ProcDump for Mac is part of [Sysinternals](https://sysinternals.com).
 3 | 
 4 | # Installation & Usage
 5 | 
 6 | ## Requirements
 7 | * Minimum OS: Sierra
 8 | 
 9 | ## Install ProcDump
10 | To install ProcDump for Mac, you'll need to install [Homebrew](https://brew.sh) if you haven't already.
11 | 
12 | 1. Add the Sysinternals tap:
13 |    ```bash
14 |    brew tap Microsoft/sysinternalstap
15 |    ```
16 |    
17 | 1. Install individual Sysinternals tools:
18 |    ```bash
19 |    brew install procdump
20 |    ```
21 | 
22 | ## Build
23 | ProcDump for Mac is based on the ProcDump for Linux code base which is located [here](BUILD.md).
24 | 
25 | ## Usage
26 | ```
27 | Capture Usage: 
28 |    procdump [-n Count]
29 |             [-s Seconds]
30 |             [-c|-cl CPU_Usage]
31 |             [-m|-ml Commit_Usage1[,Commit_Usage2...]]
32 |             [-tc Thread_Threshold]
33 |             [-fc FileDescriptor_Threshold]
34 |             [-pf Polling_Frequency]
35 |             [-o]
36 |             [-log syslog|stdout]
37 |             {
38 |              {{[-w] Process_Name | PID} [Dump_File | Dump_Folder]}
39 |             }
40 | 
41 | Options:
42 |    -n      Number of dumps to write before exiting.
43 |    -s      Consecutive seconds before dump is written (default is 10).
44 |    -c      CPU threshold above which to create a dump of the process.
45 |    -cl     CPU threshold below which to create a dump of the process.
46 |    -tc     Thread count threshold above which to create a dump of the process.
47 |    -fc     File descriptor count threshold above which to create a dump of the process.
48 |    -pf     Polling frequency.
49 |    -o      Overwrite existing dump file.
50 |    -log    Writes extended ProcDump tracing to the specified output stream (syslog or stdout).
51 |    -w      Wait for the specified process to launch if it's not running.```
52 | ```
53 | ### Examples
54 | > The following examples all target a process with pid == 1234
55 | 
56 | The following will create a core dump immediately.
57 | ```
58 | sudo procdump 1234
59 | ```
60 | The following will create 3 core dumps 10 seconds apart.
61 | ```
62 | sudo procdump -n 3 1234
63 | ```
64 | The following will create 3 core dumps 5 seconds apart.
65 | ```
66 | sudo procdump -n 3 -s 5 1234
67 | ```
68 | The following will create a core dump each time the process has CPU usage >= 65%, up to 3 times, with at least 10 seconds between each dump.
69 | ```
70 | sudo procdump -c 65 -n 3 1234
71 | ```
72 | The following will create a core dump each time the process has CPU usage >= 65%, up to 3 times, with at least 5 seconds between each dump.
73 | ```
74 | sudo procdump -c 65 -n 3 -s 5 1234
75 | ```
76 | The following will create a core dump when CPU usage is outside the range [10,65].
77 | ```
78 | sudo procdump -cl 10 -c 65 1234
79 | ```
80 | The following will create a core dump when CPU usage is >= 65% or memory usage is >= 100 MB.
81 | ```
82 | sudo procdump -c 65 -m 100 1234
83 | ```
84 | 
85 | # License
86 | Copyright (c) Microsoft Corporation. All rights reserved.
87 | 
88 | Licensed under the MIT License.
89 | 


--------------------------------------------------------------------------------