1# crash_reporter
2
3`crash_reporter` is a deamon running on the device that saves the call stack of
4crashing programs. It makes use of the
5[Breakpad](https://chromium.googlesource.com/breakpad/breakpad/) library.
6
7During a build, Breakpad symbol files are generated for all binaries.  They are
8packaged into a zip file when running `m dist`, so that a developer can upload
9them to the crash server.
10
11On a device, if the user has opted in to metrics and crash reporting, a
12Breakpad minidump is generated when an executable crashes, which is then
13uploaded to the crash server.
14
15On the crash server, it compares the minidump's signature to the symbol files
16that the developer has uploaded, and extracts and symbolizes the stack trace
17from the minidump.
18
19## SELinux policies
20
21In order to correctly generate a minidump, `crash_reporter` needs to be given
22the proper SELinux permissions for accessing the domain of the crashing
23executable.  By default, `crash_reporter` has only been given access to a select
24number of system domains, such as `metricsd`, `weave`, and `update_engine`.  If
25a developer wants their executable's crashes to be caught by `crash_reporter`,
26they will have to set their SELinux policies in their .te file to allow
27`crash_reporter` access to their domain.  This can be done through a simple
28[macro](https://android.googlesource.com/device/generic/brillo/+/master/sepolicy/te_macros):
29
30    allow_crash_reporter(domain_name)
31
32Replace *domain_name* with whatever domain is assigned to the executable in
33the `file_contexts` file.
34
35## Configuration
36
37`crash_reporter` has a few different configuration options that have to be set.
38
39- Crashes are only handled and uploaded if analytics reporting is enabled,
40  either via the weave call to set `_metrics.enableAnalyticsReporting` or by
41  manually creating the file `/data/misc/metrics/enabled` (for testing only).
42- The `BRILLO_CRASH_SERVER` make variable should be set in the `product.mk`
43  file to the URL of the crash server.  For Brillo builds, it is set
44  automatically through the product configuration.  Setting this variable will
45  populate the `/etc/os-release.d/crash_server` file on the device, which is
46  read by `crash_sender`.
47- The `BRILLO_PRODUCT_ID` make variable should be set in the `product.mk` file
48  to the product's ID.  For Brillo builds, it is set automatically through the
49  product configuration.  Setting this variable will populate the
50  `/etc/os-release.d/product_id`, which is read by `crash_sender`.
51
52## Uploading crash reports in *eng* builds
53
54By default, crash reports are only uploaded to the server for production
55*user* and *userdebug* images.  In *eng* builds, with crash reporting enabled
56the device will generate minidumps for any crashing executables but will not
57send them to the crash server.  If a developer does want to force an upload,
58they can do so by issuing the command `SECONDS_SEND_SPREAD=5 FORCE_OFFICIAL=1
59crash_sender` from an ADB shell.  This will send the report to the server, with
60the *image_type* field set to *force-official* so that these reports can be
61differentiated from normal reports.
62