Bugreport file format

This document specifies the format of the bugreport files generated by the bugreport services (like bugreport and bugreportplus) and delivered to the end user (i.e., it doesn’t include other tools like adb bugreport).

A bugreport is initially generated by dumpstate, then processed by Shell, which in turn delivers it to the end user through a ACTION_SEND_MULTIPLE intent; the end user then select which app (like an email client) handles such intent.

Text file (Pre-M)

Prior to Android M (Marshmallow), dumpstate generates a flat .txt file named bugreport-DATE.txt (where DATE is date the bugreport was generated, in the format YYYY-MM-DD-HH-MM-SS), and Shell simply propagates it as an attachment in the ACTION_SEND_MULTIPLE intent.

Version 0 (Android M)

On Android M (Marshmallow), dumpstate still generates a flat bugreport-DATE.txt file, but then Shell creates a zip file called bugreport-DATE.zip containing a bugreport-DATE.txt entry and sends that file as the ACTION_SEND_MULTIPLE attachment.

Version 1.0 (Android N)

On Android N (TBD), dumpstate generates a zip file directly (unless there is a failure, in which case it reverts to the flat file that is zipped by Shell and hence the end result is the v0 format).

The zip file is by default called bugreport-BUILD_ID-DATE.zip and it contains a bugreport-BUILD_ID-DATE.txt entry, although the end user can change the name (through Shell), in which case they would be called bugreport-BUILD_ID-NEW_NAME.zip and bugreport-BUILD_ID-NEW_NAME.txt respectively.

The zip file also contains 2 metadata entries generated by dumpstate:

  • version.txt: whose value is 1.0.
  • main-entry.txt: whose value is the name of the flat text entry (i.e., bugreport-BUILD_ID-DATE.txt or bugreport-NEW_NAME.txt).

dumpstate can also copy files from the device’s filesystem into the zip file under the FS folder. For example, a /dirA/dirB/fileC file in the device would generate a FS/dirA/dirB/fileC entry in the zip file.

When systrace is enabled, the zip file will contain a systrace.txt file as well.

The flat file also has some minor changes:

  • Tombstone files were removed and added to the zip file.
  • The duration of each section is printed in the report.
  • Some dumpsys sections (memory and cpuinfo) are reported earlier in the file.

Besides the files generated by dumpstate, Shell can also add 2 other files upon the end user’s request:

  • title.txt: whose value is a single-line summary of the problem.
  • description.txt: whose value is a multi-line, detailed description of the problem.

Intermediate versions

During development, the versions will be suffixed with -devX or -devX-EXPERIMENTAL_FEATURE, where X is a number that increases as the changes become stable.

For example, the initial version during Android N development was 1.0-dev1. When dumpsys was split in 2 sections but not all tools were ready to parse that format, the version was named 1.0-dev2, which had to be passed do dumpsys explicitly (i.e., trhough a -V 1.0-dev2 argument). Once that format became stable and tools knew how to parse it, the default version became 1.0-dev2.

Similarly, if changes in the file format are made after the initial release of Android defining that format, then a new sub-version will be used. For example, if after Android N launches changes are made for the next N release, the version will be called 1.1 or something like that.

Determining version and main entry

Tools parsing the zipped bugreport file can use the following algorithm to determine the bugreport format version and its main entry:

If [entries contain "version.txt"]
   version = read("version.txt")
   main_entry = read("main_entry.txt")
else
   version = 0
   main_entry = entries[0]
fi