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 (Nougat), 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.

Android O versions

On Android O (Oreo), the following changes were made:

  • The ANR traces are added to the FS folder, typically under FS/data/anr (version 2.0-dev-split-anr).

Version 2.0 (Android P)

On Android P, the following changes were made:

  • Framework services are dumped by priority. Supported priorities can be specified when registering the service. If a service does not specify its priority, its assumed to be NORMAL. Supported priorities:

    • CRITICAL - services that must dump first, and fast (under 100ms). Ex: cpuinfo.
    • HIGH - services that also must dump first, but can take longer (under 250ms) to dump. Ex: meminfo.
    • NORMAL - services that have no rush to dump and can take a long time (under 10s).

    Format changes:

    • Two additional dumpsys sections are generated. The two new sections can be identified by their HEADER DUMPSYS CRITICAL and DUMPSYS HIGH.
    • Services in the new sections will have a new header containing the priority. DUMP OF SERVICE CRITICAL <servicename> and DUMP OF SERVICE HIGH <servicename>. For example, cpuinfo will now move to DUMPSYS CRITICAL and will have a header DUMP OF SERVICE CRITICAL CPUINFO.

  • Bug report will contain proto dumps from all supporting services. Support can be specified when registering framework services. Format changes:

    • All protos will be generated into separate files per service, per priority. The files will be stored in proto/<servicename>(_CRITICAL|_HIGH|).proto

  • ANR trace feature has been pushed to version 3.0-dev-split-anr

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 to dumpsys explicitly (by setting the dumpstate.version system property). 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