1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/crashreporter/docs/index.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,169 @@
1.4 +==============
1.5 +Crash Reporter
1.6 +==============
1.7 +
1.8 +Overview
1.9 +========
1.10 +
1.11 +The **crash reporter** is a subsystem to record and manage application
1.12 +crash data.
1.13 +
1.14 +While the subsystem is known as *crash reporter*, it helps to think of
1.15 +it more as a *process dump manager*. This is because the heart of this
1.16 +subsystem is really managing process dump files and these files are
1.17 +created not only from process crashes but also from hangs and other
1.18 +exceptional events.
1.19 +
1.20 +The crash reporter subsystem is composed of a number of pieces working
1.21 +together.
1.22 +
1.23 +Breakpad
1.24 + Breakpad is a library and set of tools to make collecting process
1.25 + information (notably dumps from crashes) easy. Breakpad is a 3rd
1.26 + party project (originaly developed by Google) that is imported into
1.27 + the tree.
1.28 +
1.29 +Dump files
1.30 + Breakpad produces files called *dump files* that hold process data
1.31 + (stacks, heap data, etc).
1.32 +
1.33 +Crash Reporter Client
1.34 + The crash reporter client is a standalone executable that is launched
1.35 + to handle dump files. This application optionally submits crashes to
1.36 + Mozilla (or the configured server).
1.37 +
1.38 +How Main-Process Crash Handling Works
1.39 +=====================================
1.40 +
1.41 +The crash handler is hooked up very early in the Gecko process lifetime.
1.42 +It all starts in ``XREMain::XRE_mainInit()`` from ``nsAppRunner.cpp``.
1.43 +Assuming crash reporting is enabled, this startup function registers an
1.44 +exception handler for the process and tells the crash reporter subsystem
1.45 +about basic metadata such as the application name and version.
1.46 +
1.47 +The registration of the crash reporter exception handler doubles as
1.48 +initialization of the crash reporter itself. This happens in
1.49 +``CrashReporter::SetExceptionHandler()`` from ``nsExceptionHandler.cpp``.
1.50 +The crash reporter figures out what application to use for reporting
1.51 +dumped crashes and where to store these dump files on disk. The Breakpad
1.52 +exception handler (really just a mechanism for dumping process state) is
1.53 +initialized as part of this function. The Breakpad exception handler is
1.54 +a ``google_breakpad::ExceptionHandler`` instance and it's stored as
1.55 +``gExceptionHandler``.
1.56 +
1.57 +As the application runs, various other systems may write *annotations*
1.58 +or *notes* to the crash reporter to indicate state of the application,
1.59 +help with possible reasons for a current or future crash, etc. These are
1.60 +performed via ``CrashReporter::AnnotateCrashReport()`` and
1.61 +``CrashReporter::AppendAppNotesToCrashReport()`` from
1.62 +``nsExceptionHandler.h``.
1.63 +
1.64 +For well running applications, this is all that happens. However, if a
1.65 +crash or similar exceptional event occurs (such as a hang), we need to
1.66 +write a crash report.
1.67 +
1.68 +When an event worthy of writing a dump occurs, the Breakpad exception
1.69 +handler is invoked and Breakpad does its thing. When Breakpad has
1.70 +finished, it calls back into ``CrashReporter::MinidumpCallback()`` from
1.71 +``nsExceptionHandler.cpp`` to tell the crash reporter about what was
1.72 +written.
1.73 +
1.74 +``MinidumpCallback()`` performs a number of actions once a dump has been
1.75 +written. It writes a file with the time of the crash so other systems can
1.76 +easily determine the time of the last crash. It supplements the dump
1.77 +file with an *extra* file containing Mozilla-specific metadata. This data
1.78 +includes the annotations set via ``CrashReporter::AnnotateCrashReport()``
1.79 +as well as time since last crash, whether garbage collection was active at
1.80 +the time of the crash, memory statistics, etc.
1.81 +
1.82 +If the *crash reporter client* is enabled, ``MinidumpCallback()`` invokes
1.83 +it. It simply tries to create a new *crash reporter client* process (e.g.
1.84 +*crashreporter.exe*) with the path to the written minidump file as an
1.85 +argument.
1.86 +
1.87 +The *crash reporter client* performs a number of roles. There's a lot going
1.88 +on, so you may want to look at ``main()`` in ``crashreporter.cpp``. First,
1.89 +it verifies the dump data is sane. If it isn't (e.g. required metadata is
1.90 +missing), the dump data is ignored. If dump data looks sane, the dump data
1.91 +is moved into the *pending* directory for the configured data directory
1.92 +(defined via the ``MOZ_CRASHREPORTER_DATA_DIRECTORY`` environment variable
1.93 +or from the UI). Once this is done, the main crash reporter UI is displayed
1.94 +via ``UIShowCrashUI()``. The crash reporter UI is platform specific: there
1.95 +are separate versions for Windows, OS X, and various \*NIX presentation
1.96 +flavors (such as GTK). The basic gist is a dialog is displayed to the user
1.97 +and the user has the opportunity to submit this dump data to a remote
1.98 +server.
1.99 +
1.100 +If a dump is submitted via the crash reporter, the raw dump files are
1.101 +removed from the *pending* directory and a file containing the
1.102 +crash ID from the remote server for the submitted dump is created in the
1.103 +*submitted* directory.
1.104 +
1.105 +If the user chooses not to submit a dump in the crash reporter UI, the dump
1.106 +files are deleted.
1.107 +
1.108 +And that's pretty much what happens when a crash/dump is written!
1.109 +
1.110 +Plugin and Child Process Crashes
1.111 +================================
1.112 +
1.113 +Crashes in plugin and child processes are also managed by the crash
1.114 +reporting subsystem.
1.115 +
1.116 +Child process crashes are handled by the ``mozilla::dom::CrashReporterParent``
1.117 +class defined in ``dom/ipc``. When a child process crashes, the toplevel IPDL
1.118 +actor should check for it by calling TakeMinidump in its ``ActorDestroy``
1.119 +Method: see ``mozilla::plugins::PluginModuleParent::ActorDestroy`` and
1.120 +``mozilla::plugins::PluginModuleParent::ProcessFirstMinidump``. That method
1.121 +is responsible for calling
1.122 +``mozilla::dom::CrashReporterParent::GenerateCrashReportForMinidump`` with
1.123 +appropriate crash annotations specific to the crash. All child-process
1.124 +crashes are annotated with a ``ProcessType`` annotation, such as "content" or
1.125 +"plugin".
1.126 +
1.127 +Submission of child process crashes is handled by application code. This
1.128 +code prompts the user to submit crashes in context-appropriate UI and then
1.129 +submits the crashes using ``CrashSubmit.jsm``.
1.130 +
1.131 +Flash Process Crashes
1.132 +=====================
1.133 +
1.134 +On Windows Vista+, the Adobe Flash plugin creates two extra processes in its
1.135 +Firefox plugin to implement OS-level sandboxing. In order to catch crashes in
1.136 +these processes, Firefox injects a crash report handler into the process using the code at ``InjectCrashReporter.cpp``. When these crashes occur, the
1.137 +ProcessType=plugin annotation is present, and an additional annotation
1.138 +FlashProcessDump has the value "Sandbox" or "Broker".
1.139 +
1.140 +Plugin Hangs
1.141 +============
1.142 +
1.143 +Plugin hangs are handled as crash reports. If a plugin doesn't respond to an
1.144 +IPC message after 60 seconds, the plugin IPC code will take minidumps of all
1.145 +of the processes involved and then kill the plugin.
1.146 +
1.147 +In this case, there will be only one .ini file with the crash report metadata,
1.148 +but there will be multiple dump files: at least one for the browser process and
1.149 +one for the plugin process, and perhaps also additional dumps for the Flash
1.150 +sandbox and broker processes. All of these files are submitted together as a
1.151 +unit. Before submission, the filenames of the files are linked:
1.152 +
1.153 +- **uuid.ini** - *annotations, includes an additional_minidumps field*
1.154 +- **uuid.dmp** - *plugin process dump file*
1.155 +- **uuid-<other>.dmp** - *other process dump file as listed in additional_minidumps*
1.156 +
1.157 +Browser Hangs
1.158 +=============
1.159 +
1.160 +There is a feature of Firefox that will crash Firefox if it stops processing
1.161 +messages after a certain period of time. This feature doesn't work well and is
1.162 +disabled by default. See ``xpcom/threads/HangMonitor.cpp``. Hang crashes
1.163 +are annotated with ``Hang=1``.
1.164 +
1.165 +about:crashes
1.166 +=============
1.167 +
1.168 +If the crash reporter subsystem is enabled, the *about:crashes*
1.169 +page will be registered with the application. This page provides
1.170 +information about previous and submitted crashes.
1.171 +
1.172 +It is also possible to submit crashes from *about:crashes*.
