README.md
1 # crash_reporter 2 3 `crash_reporter` is a deamon running on the device that saves the call stack of 4 crashing programs. It makes use of the 5 [Breakpad](https://chromium.googlesource.com/breakpad/breakpad/) library. 6 7 During a build, Breakpad symbol files are generated for all binaries. They are 8 packaged into a zip file when running `m dist`, so that a developer can upload 9 them to the crash server. 10 11 On a device, if the user has opted in to metrics and crash reporting, a 12 Breakpad minidump is generated when an executable crashes, which is then 13 uploaded to the crash server. 14 15 On the crash server, it compares the minidump's signature to the symbol files 16 that the developer has uploaded, and extracts and symbolizes the stack trace 17 from the minidump. 18 19 ## SELinux policies 20 21 In order to correctly generate a minidump, `crash_reporter` needs to be given 22 the proper SELinux permissions for accessing the domain of the crashing 23 executable. By default, `crash_reporter` has only been given access to a select 24 number of system domains, such as `metricsd`, `weave`, and `update_engine`. If 25 a developer wants their executable's crashes to be caught by `crash_reporter`, 26 they 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 32 Replace *domain_name* with whatever domain is assigned to the executable in 33 the `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 54 By default, crash reports are only uploaded to the server for production 55 *user* and *userdebug* images. In *eng* builds, with crash reporting enabled 56 the device will generate minidumps for any crashing executables but will not 57 send them to the crash server. If a developer does want to force an upload, 58 they can do so by issuing the command `SECONDS_SEND_SPREAD=5 FORCE_OFFICIAL=1 59 crash_sender` from an ADB shell. This will send the report to the server, with 60 the *image_type* field set to *force-official* so that these reports can be 61 differentiated from normal reports. 62
