Gaia/Email/SecretDebugMode

It's a secret to everybody... who has not read this wiki page.

What's so cool about the secret debug menu?

The secret debug menu exposes logging functionality for debugging and diagnosis. It produces JSON log files.

By default, logging starts out in a minimal no-op mode. Events/errors are counted, everything else is discarded. There are two additional modes of logging: "general", and test mode. "general" is what gets enabled in the e-mail app and is intended to only log non-sensitive data. In test mode, additional arguments are logged to provide a more comprehensive understanding of the system is doing.

For example, the log definition for the IMAP protocol connection, eliding other entry definitions etc, looks like:

 var LOGFAB = exports.LOGFAB = $log.register(module, {
   ImapProtoConn: {
     events: {
       data: { length: false },
     },
     TEST_ONLY_events: {
       // This may be a Buffer and therefore need to be coerced
       data: { data: $log.TOSTRING },
     },
 }); // end LOGFAB

The logging code then looks like:

 if (self._LOG) self._LOG.data(chunk.length, chunk);

In the default and "general" logging modes, 'chunk' gets ignored and is not touched by the logging method. Only when run in unit test mode is the data captured.

Toggling the setting changes the configuration in the IndexedDB database which is loaded and takes effect only at app startup. When enabled, a setInterval callback is added that fires every 1 second to check for new log entries and put them in a bin allocated to that second. If there were any entries, they are added to a list that is used to only keep the 30 most recent seconds with log entries.

Getting to the Secret Debug Menu

• Bring up the settings page.
  • The settings page is only accessible once an account has been added, so you may need to add a fake account. In the event we have removed the fake account button, you can manually create a fake account by creating an e-mail account like "foo@example.com". It will not require you to authenticate, but is not very realistic.
  • The settings page is accessed via the gear icon on the folder list page. You access the folder list by clicking the parallel lines icon in the upper left.
• On the settings page, click the "v1" text at the very bottom of the screen 5 times within 2 seconds. You will probably need to scroll to get there.

Enabling Logging that does not entrain user data (general mode)

• (Bring up the secret debug menu)
• Turn on logging by pressing the button that says "Logging is DISABLED; toggle". It will change to say "Logging is ENABLED; toggle" if the click was processed.
• Reset the application by pushing the "Reset app" button. This is required in order to force the application to restart with logging active.

An example of general logging can be seen here: pretty UI raw JSON prettified JSON

Enabling logging that DOES ENTRAIN USER DATA (test mode)

• (Bring up the secret debug menu)
• (Enable logging)
• Turn on test mode by clicking on the button that says "logging is SAFE; toggle". It should now read "logging DANGEROUSLY ENTRAINS USER DATA; toggle".
• Reset the application by pushing the "Reset app" button. This is required in order to force the application to restart with the new logging settings active.

Dumping log files to disk

We write log files to device storage so you can grab them via adb. Unfortunately, device storage is a bit strict about what it allows you to store right now. So we name our files along the lines of gem-log-TIMESTAMP.json.rm where "TIMESTAMP" is Date.now().

• (Bring up the secret debug menu)
• Press the button labeled "Dump log to storage". You know it heard you because it will bring up an annoying 'device-storage:videos' prompt.
• click yes on the permission to write to device-storage:videos.
• Your file should now be named gem-log-TIMESTAMP.json.rm and be in devicestorage somewhere.

Getting the log files out

Here is a script that works for me on a computer with a device attached to grab the file to /tmp/gem-log.json:

 #!/bin/bash
 set -o errexit
 set -o pipefail
 
 # maybe grep instead of
 logpath=`adb shell ls /mnt/sdcard/DCIM/gem-log-*.rm | head -1 | tr -d '\n\r'`
 echo I am grabbing: $logpath
 adb pull ${logpath} /tmp/gem-log.json
 adb shell rm $logpath

Here is a script that works for me when using b2g-desktop on linux:

 #!/bin/bash
 set -o errexit
 set -o pipefail
 
 # maybe grep instead of
 logpath=`ls ~/Videos/gem-log-*.rm | head -1 | tr -d '\n\r'`
 echo I am grabbing: $logpath
 mv ${logpath} /tmp/gem-log.json
 chmod a+r /tmp/gem-log.json

Interpreting the log files

You may just want to provide the JSON file to the developers of the e-mail application. But if you don't, here is what you do:

Check out a copy of arbitrarypushlog and build the standalone mode with a "?log=PATHTOLOG" argument, keeping in mind that you may need to host both the source and the log file at the same origin in order for things to work if the log file is not served with blanket CORS permissions.

Alternatively, you can either use the index.html referenced above with "?log=LOGURL" appended or copy the files that make it up to wherever you want and CORS is not a problem.