capturing_minidump.rst (10921B)
1 Capturing a minidump 2 ==================== 3 4 *Minidumps* are files created by various Windows tools which record the 5 complete state of a program as it's running, or as it was at the moment 6 of a crash. Small minidumps are created by the Breakpad :ref:`crash 7 reporting <Crash Reporter>` tool, but sometimes that's not 8 sufficient to diagnose a problem. For example, if the application is 9 hanging (not responding to input, but hasn't crashed) then Breakpad is 10 not triggered, and it can be difficult to determine where the problem 11 lies. Sometimes a more complete form of minidump is needed to see 12 additional details about a crash, in which case manual capture of a 13 minidump is desired. 14 15 This page describes how to capture these minidumps on Windows, to permit 16 better debugging. 17 18 19 Privacy and minidumps 20 --------------------- 21 22 .. warning:: 23 24 **Warning!** Unlike the minidumps submitted by Breakpad, these 25 minidumps contain the **complete** contents of program memory. They 26 are therefore much more likely to contain private information, if 27 there is any in the browser. For this reason, you may prefer to 28 generate minidumps against a `clean 29 profile <http://support.mozilla.com/en-US/kb/Managing%20profiles>`__ 30 where possible. 31 32 33 Capturing a minidump: application crash 34 --------------------------------------- 35 36 To capture a full minidump for an application crash, you can use a tool called 37 **Debugging Tools for Windows**, which is provided by Microsoft for free. 38 39 40 Install Debugging Tools for Windows 41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 42 43 Please follow `these instructions 44 <https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/>`__. 45 You can install the Debugging Tools for Windows alone, but you cannot 46 download it alone. To install it, download Windows Software Development Kit 47 (SDK) first, start the installer, and then select only **Debugging Tools for 48 Windows** in the list of features to install. 49 50 .. image:: img/sdk-installer.png 51 52 The latest installer installs the tools for all CPU architectures (X86, 53 X64, ARM, and ARM64). You need to choose a tool of the architecture 54 matching Firefox you want to capture a minidump from. For example, if 55 you want to capture a minidump from 32-bit Firefox on 64-bit Windows, 56 use the X86 version of tools, not X64 tools. 57 58 The default install path of SDK for 64-bit Windows is 59 ``%ProgramFiles(x86)%\Windows Kits\10``. The debugging tools can be found in 60 the folder named **Debuggers** under your install path of SDK. 61 62 The Debugging Tools for Windows contains both graphical and command line 63 debugging tools that can be used to capture a minidump. If you prefer 64 a graphical tool, please follow `Capture a minidump in a graphical way 65 <#capture-a-minidump-in-a-graphical-way>`__. If you prefer a command 66 line tool, please follow `Capture a minidump from the command line 67 <#capture-a-minidump-from-the-command-line>`__. 68 69 70 Capture a minidump in a graphical way 71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 72 #. Launch the graphical debugger named WinDbg from the Start Menu. WinDbg 73 icons are registered under "Windows Kits" as below. 74 75 |WinDbg in Start Menu| 76 77 #. Connect Firefox to the debugger. 78 79 a. If Firefox is not already running, open the **"File"** menu on WinDbg 80 and choose **"Open Executable..."**. In the file chooser window that 81 appears, open the firefox.exe executable. If you're not sure about where 82 it is, please see `How to find the location of firefox.exe 83 <#how-to-find-the-location-of-firefox-exe>`__. 84 85 b. If Firefox is already running and you know which process you want to 86 capture a minidump from, open the **"File"** menu on WinDbg and choose 87 **"Attach to a Process..."**. In the "Attach to Process" dialog that 88 appears, select the process. To identify a process, please see 89 `Identify a process to attach a debugger to 90 <#identify-a-process-to-attach-a-debugger-to>`__. 91 92 #. You should now see a "Command" text window with debug output at the 93 top and an input box at the bottom. From the menu, select 94 ``Debug → Go``, and Firefox should start. If the debugger spits out 95 some text right away and Firefox doesn't come up, select 96 ``Debug → Go`` again. 97 98 #. When the program is about to crash, WinDbg will spit out more data, 99 and the prompt at the bottom will change from saying "``*BUSY*``" to 100 having a number in it. At this point, you should type 101 "``.dump /ma c:\temp\firefoxcrash.dmp``" -- without the quotes, but 102 don't forget the dot at the beginning. Once it completes, which can 103 take a fair while, you will have a very large file at 104 ``c:\temp\firefoxcrash.dmp`` that can be used to help debug your 105 problem. File size will depend on this size of Firefox running in 106 your environment, which could several GB. 107 108 #. Ask in the relevant bug or thread how best to share this very large 109 file! 110 111 112 Capture a minidump from the command line 113 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 114 115 If Firefox is not already running, open the Command Prompt and run the following 116 command. This command launches all Firefox processes under a debugger. This 117 technique is useful when you have a startup crash or when you're not sure about 118 which process will crash. 119 120 To find out where firefox.exe is, please see `How to find the location 121 of firefox.exe <#how-to-find-the-location-of-firefox-exe>`__. 122 123 .. code:: 124 125 <path to debugger>\cdb.exe -g -G -o <path to firefox>\firefox.exe 126 127 128 For example, if both the debugging tools and Firefox are installed in the 129 default folder and you want to capture a minidump of 64-bit Firefox, 130 the command will be like this. Please note that you need to add double 131 quotes when a path contains one or more whitespaces. 132 133 .. code:: 134 135 "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe" -g -G -o "C:\Program Files\Mozilla Firefox\firefox.exe" 136 137 138 If a Firefox process you want to capture a minidump from is already running, 139 attach the debugger to it with the following command. To identify a process, 140 please see `Identify a process to attach a debugger to 141 <#identify-a-process-to-attach-a-debugger-to>`__. 142 143 .. code:: 144 145 <path to debugger>\cdb.exe -g -G -p <PID> 146 147 When the process crashes, the debugger tool captures it and waits for your 148 command. At this point, you should type ``.dump /ma c:\temp\firefoxcrash.dmp`` 149 -- don't forget the dot at the beginning. Once it completes, which can take 150 a fair while, you will have a very large file at ``c:\temp\firefoxcrash.dmp`` 151 that can be used to help debug your problem. File size will depend on this 152 size of Firefox running in your environment, which could several GB. 153 154 After a minidump is generated, type ``q`` and press Enter to quit the debugger. 155 156 157 Capturing a minidump: application hang 158 -------------------------------------- 159 160 On Windows Vista and Windows 7, you can follow `these 161 instructions <http://support.microsoft.com/kb/931673>`__ to capture a 162 dump file and locate it after it's been saved. 163 164 165 Identify a process to attach a debugger to 166 ------------------------------------------ 167 168 When you're running Firefox, even if you have only a single tab, you may have 169 noticed a bunch of firefox.exe instances in Task Manager. This means Firefox 170 consists of multiple processes. Since an application crash happens per process 171 and a minidump is generated per process, you need to identify which process will 172 crash before starting a debugger. 173 174 Identify a process type 175 ~~~~~~~~~~~~~~~~~~~~~~~ 176 177 Each instance of firefox.exe has a type. To identify a process to attach 178 a debugger to, you need to know its process type first. 179 180 When a crash happens, if all Firefox windows are suddenly gone and Mozilla 181 Crash Reporter window is opend, a process that crashed is the main process. 182 183 .. image:: img/crashreporter.png 184 185 When a crash happens, if you see the following page, a process that crashed 186 is a tab (content) process. 187 188 .. image:: img/tabcrashed.png 189 190 There are more process types, but there isn't an easy way to detect a crash in 191 a process of those types because the symptom varies. If you cannot be sure 192 about the type of a crashing process, terminate Firefox and launch a new 193 instance of Firefox under a debugger in the way described above. 194 195 If a GPU process crashes, you may see a window is not rendered correctly as 196 below. Since the main process relaunches a GPU process, this symptom will be 197 transient and the window will be rendered correctly again. 198 199 .. image:: img/crash-gpu.png 200 201 If a GMP (= Gecko Media Plugin) process crashes, you will see an information 202 bar will be displayed below the address bar. 203 204 .. image:: img/crash-gmp.png 205 206 If an RDD (= Remote Data Decoder) process crashes, Firefox may stop playing 207 a video as below, but not limited to this symptom. 208 209 .. image:: img/crash-rdd.png 210 211 212 Identify a process ID (PID) 213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 214 215 Once you understand what type of process crashes, the next step is to get a 216 process ID (PID), which is a value to specify in the debugger command we 217 discussed above. We present two ways to get a PID here. 218 219 The first way is to use Firefox itself. Open a new tab and go to the 220 **about:processes** page. This page shows the list of all processes and their 221 PIDs. In the example below, the PID of the main process is **6308** and the 222 PID of the tab process hosting a page of mozilla.org is **6748**. 223 224 .. image:: img/about-processes.png 225 226 The second way is to use `Process Explorer 227 <https://docs.microsoft.com/en-us/sysinternals/downloads/process-explorer>`__, 228 which is provided by Microsoft for free. You may need this technique to attach 229 a debugger to a hung process or when you cannot open a new tab in the existing 230 Firefox for some reason. 231 232 Process Explorer is basically an advanced version of Task Manager. Since it 233 displays processes in a hierarchical tree view, you can easily locate the main 234 process, which is the parent of all child processes. In the example below, the 235 PID of the main process is **6308** and all processes, including 236 plugin-container.exe, under the main process is child processes. 237 238 Another helpful feature of Process Explorer is that when you hover the mouse 239 cursor on a process, it displays a tooltip window showing the process's command 240 line string. For a child process of firefox.exe, the command line's last 241 keyword shows the process type, so you can tell which process is which process 242 type. In the example below, the tooltip window displays a command line string 243 of a GPU process. 244 245 .. image:: img/process-explorer.png 246 247 248 How to find the location of firefox.exe 249 --------------------------------------- 250 251 If you're not sure about the location of the executable file (firefox.exe) of 252 Firefox you run, you can find it in the **about:support** page. In the 253 "Application Basics" section, the path to firefox.exe is displayed in the row 254 of "Application Binary". 255 256 .. image:: img/about-support.png 257 258 .. |WinDbg in Start Menu| image:: img/windbg-in-startmenu.png 259 :width: 50%