1# Bugreport file format
2
3This document specifies the format of the bugreport files generated by the
4bugreport services (like `bugreport` and `bugreportplus`) and delivered to the
5end user (i.e., it doesn’t include other tools like `adb bugreport`).
6
7A _bugreport_ is initially generated by dumpstate, then processed by **Shell**,
8which in turn delivers it to the end user through a `ACTION_SEND_MULTIPLE`
9intent; the end user then select which app (like an email client) handles such
10intent.
11
12## Text file (Pre-M)
13Prior 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
15format _YYYY-MM-DD-HH-MM-SS_), and Shell simply propagates it as an attachment
16in the `ACTION_SEND_MULTIPLE` intent.
17
18## Version 0 (Android M)
19On _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
22file as the `ACTION_SEND_MULTIPLE` attachment.
23
24## Version 1.0 (Android N)
25On _Android N (TBD)_, `dumpstate` generates a zip file directly (unless there
26is 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
29The 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
34The 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 device’s filesystem into the zip file
41under the `FS` folder. For example, a `/dirA/dirB/fileC` file in the device
42would generate a `FS/dirA/dirB/fileC` entry in the zip file.
43
44When systrace is enabled, the zip file will contain a `systrace.txt` file as well.
45
46The 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
52Besides the files generated by `dumpstate`, **Shell** can also add 2 other
53files upon the end user’s 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## Intermediate versions
59During development, the versions will be suffixed with _-devX_ or
60_-devX-EXPERIMENTAL_FEATURE_, where _X_ is a number that increases as the
61changes become stable.
62
63For example, the initial version during _Android N_ development was
64**1.0-dev1**. When `dumpsys` was split in 2 sections but not all tools were
65ready to parse that format, the version was named **1.0-dev2**,
66which had to be passed do `dumpsys` explicitly (i.e., trhough a
67`-V 1.0-dev2` argument). Once that format became stable and tools
68knew how to parse it, the default version became **1.0-dev2**.
69
70Similarly, if changes in the file format are made after the initial release of
71Android defining that format, then a new _sub-version_ will be used.
72For example, if after _Android N_ launches changes are made for the next _N_
73release, the version will be called **1.1** or something like that.
74
75Determining version and main entry
76-----------------------------------------------
77
78Tools parsing the zipped bugreport file can use the following algorithm to
79determine the bugreport format version and its main entry:
80
81```
82If [entries contain "version.txt"]
83   version = read("version.txt")
84   main_entry = read("main_entry.txt")
85else
86   version = 0
87   main_entry = entries[0]
88fi
89```
90