1 # Bugreport file format 2 3 This document specifies the format of the bugreport files generated by the 4 bugreport services (like `bugreport` and `bugreportplus`) and delivered to the 5 end user (i.e., it doesnt include other tools like `adb bugreport`). 6 7 A _bugreport_ is initially generated by dumpstate, then processed by **Shell**, 8 which in turn delivers it to the end user through a `ACTION_SEND_MULTIPLE` 9 intent; the end user then select which app (like an email client) handles such 10 intent. 11 12 ## Text file (Pre-M) 13 Prior to _Android M (Marshmallow)_, `dumpstate` generates a flat .txt file named 14 _bugreport-DATE.txt_ (where _DATE_ is date the bugreport was generated, in the 15 format _YYYY-MM-DD-HH-MM-SS_), and Shell simply propagates it as an attachment 16 in the `ACTION_SEND_MULTIPLE` intent. 17 18 ## Version 0 (Android M) 19 On _Android M (Marshmallow)_, dumpstate still generates a flat 20 _bugreport-DATE.txt_ file, but then **Shell** creates a zip file called 21 _bugreport-DATE.zip_ containing a _bugreport-DATE.txt_ entry and sends that 22 file as the `ACTION_SEND_MULTIPLE` attachment. 23 24 ## Version 1.0 (Android N) 25 On _Android N (Nougat)_, `dumpstate` generates a zip file directly (unless there 26 is a failure, in which case it reverts to the flat file that is zipped by 27 **Shell** and hence the end result is the _v0_ format). 28 29 The zip file is by default called _bugreport-BUILD_ID-DATE.zip_ and it contains a 30 _bugreport-BUILD_ID-DATE.txt_ entry, although the end user can change the name (through 31 **Shell**), in which case they would be called _bugreport-BUILD_ID-NEW_NAME.zip_ and 32 _bugreport-BUILD_ID-NEW_NAME.txt_ respectively. 33 34 The zip file also contains 2 metadata entries generated by `dumpstate`: 35 36 - `version.txt`: whose value is **1.0**. 37 - `main-entry.txt`: whose value is the name of the flat text entry (i.e., 38 _bugreport-BUILD_ID-DATE.txt_ or _bugreport-NEW_NAME.txt_). 39 40 `dumpstate` can also copy files from the devices filesystem into the zip file 41 under the `FS` folder. For example, a `/dirA/dirB/fileC` file in the device 42 would generate a `FS/dirA/dirB/fileC` entry in the zip file. 43 44 When systrace is enabled, the zip file will contain a `systrace.txt` file as well. 45 46 The flat file also has some minor changes: 47 48 - Tombstone files were removed and added to the zip file. 49 - The duration of each section is printed in the report. 50 - Some dumpsys sections (memory and cpuinfo) are reported earlier in the file. 51 52 Besides the files generated by `dumpstate`, **Shell** can also add 2 other 53 files upon the end users request: 54 55 - `title.txt`: whose value is a single-line summary of the problem. 56 - `description.txt`: whose value is a multi-line, detailed description of the problem. 57 58 ## Android O versions 59 On _Android O (Oreo)_, the following changes were made: 60 - The ANR traces are added to the `FS` folder, typically under `FS/data/anr` (version `2.0-dev-split-anr`). 61 62 ## Version 2.0 (Android P) 63 On _Android P_, the following changes were made: 64 - Framework services are dumped by priority. Supported priorities can be specified 65 when registering the service. If a service does not specify its priority, its 66 assumed to be NORMAL. 67 Supported priorities: 68 - CRITICAL - services that must dump first, and fast (under 100ms). Ex: cpuinfo. 69 - HIGH - services that also must dump first, but can take longer (under 250ms) 70 to dump. Ex: meminfo. 71 - NORMAL - services that have no rush to dump and can take a long time (under 10s). 72 73 Format changes: 74 - Two additional dumpsys sections are generated. The two new sections can be 75 identified by their HEADER `DUMPSYS CRITICAL` and `DUMPSYS HIGH`. 76 - Services in the new sections will have a new header containing the 77 priority. 78 `DUMP OF SERVICE CRITICAL <servicename>` and 79 `DUMP OF SERVICE HIGH <servicename>`. 80 For example, cpuinfo will now move to `DUMPSYS CRITICAL` and will have a 81 header `DUMP OF SERVICE CRITICAL CPUINFO`. 82 83 - Bug report will contain proto dumps from all supporting services. Support can be 84 specified when registering framework services. 85 Format changes: 86 - All protos will be generated into separate files per service, per priority. The files 87 will be stored in `proto/<servicename>(_CRITICAL|_HIGH|).proto` 88 89 - ANR trace feature has been pushed to version `3.0-dev-split-anr` 90 91 ## Intermediate versions 92 During development, the versions will be suffixed with _-devX_ or 93 _-devX-EXPERIMENTAL_FEATURE_, where _X_ is a number that increases as the 94 changes become stable. 95 96 For example, the initial version during _Android N_ development was 97 **1.0-dev1**. When `dumpsys` was split in 2 sections but not all tools were 98 ready to parse that format, the version was named **1.0-dev2**, 99 which had to be passed to `dumpsys` explicitly (by setting the `dumpstate.version` system property). 100 Once that format became stable and tools 101 knew how to parse it, the default version became **1.0-dev2**. 102 103 Similarly, if changes in the file format are made after the initial release of 104 Android defining that format, then a new _sub-version_ will be used. 105 For example, if after _Android N_ launches changes are made for the next _N_ 106 release, the version will be called **1.1** or something like that. 107 108 Determining version and main entry 109 ----------------------------------------------- 110 111 Tools parsing the zipped bugreport file can use the following algorithm to 112 determine the bugreport format version and its main entry: 113 114 ``` 115 If [entries contain "version.txt"] 116 version = read("version.txt") 117 main_entry = read("main_entry.txt") 118 else 119 version = 0 120 main_entry = entries[0] 121 fi 122 ``` 123
