From MozillaWiki
Jump to: navigation, search

<< Back to MailNews:Home Page

Mailnews logs provide data to help developers and triagers understand what is causing an issue. Please enable Thunderbird to write extra information to a log file, by setting two environment variables before running a MailNews application.

Main module options within MailNews

MailNews applications (SeaMonkey/Thunderbird) allow these CASE SENSITIVE modules/protocols in both debug and release builds. In bug 1353919 these options have been unified, the old options are in parenthesis:

  1. BayesianFilter
  2. Filters
  3. IMAP (more below)
  4. IMAPOffline (before Thunderbird version 59: IMAPOFFLINE)
  5. LDAP (before Thunderbird version 59: ldap) --- NOTE! for Thunderbird 91+ LDAP logging is changed and does not use this way of logging. There, set the mailnews.ldap.loglevel pref to "All" and open the Error Console (Ctrl+Shift+J).
  6. Mailbox (before Thunderbird version 59: MAILBOX)
  7. MailDirStore
  8. MIME
  9. MsgBiff
  10. MsgCompose (before Thunderbird version 59: msgcompose)
  11. MsgCopyService (3.3a4 nightly builds starting 5/2/2011)
  12. MsgDB (level 1=opens/closes, level 5 lists open db's on close, number of msg hdrs in use) (before Thunderbird version 59: MSGDB)
  13. MsgPurge
  14. NNTP
  15. POP3 --- NOTE! for Thunderbird 99+ POP3 logging is changed and does not use this way of logging. Staring with 99, set the mailnews.pop3.loglevel pref to "All" and open the Error Console (Ctrl+Shift+J).
  16. SMTP --- NOTE! for Thunderbird 91+ SMTP logging is changed and does not use this way of logging. Starting with 91, set the mailnews.smtp.loglevel pref to "All" and open the Error Console (Ctrl+Shift+J).

(Other options below)

Environment Variables to set

Two variables must be set. You can set them globally as system environment variables (find instructions for your OS), or as local environment variables in a batch file/script (described below), or just on the command line.

  1. MOZ_LOG - CASE SENSITIVE module name and log level separated by colon, multiple modules separated by comma, and additional options:
    • Example module and loglevel: IMAP:5,timestamp
    • ,timestamp adds a timestamp to all log lines - generally recommended. required for all timeouts and issues which need to be correlated to an action at a given time of day (as of 2009-05-13 3.0b3pre builds)
    • optional, not recommended (because it makes logging slower and affects your performance) ,sync : Buffering in log writing is disabled that so latest log data can be seen by tailing or copying the log file.
  2. MOZ_LOG_FILE - Path (with name) to the log file
    • If MOZ_LOG_FILE is not set, then the output will be logged to the console where the application was launched.
    • Since Thunderbird 70, the .moz_log extension will be added to the file name


  • The log file is written over every time you re-launch the Mozilla application.
  • If you are running multiple Mozilla applications (Firefox and Thunderbird) they may stomp on each other in the log, or even wipe out the others log entries.
  • You must have write access to the directory of the log file.

Logging level

The number in MOZ_LOG specifies the level of logging to be used. A lower number reduces the amount of information being logged. Use "5" unless requested otherwise.

  • 0 = Disabled /* Indicates logging is disabled. This should not be used directly in code. */
  • 1 = Error /* An error occurred, generally something you would consider asserting in a debug build.*/
  • 2 = Warning /* A warning often indicates an unexpected state. */
  • 3 = Info /* An informational message, often indicates the current program state. */
  • 4 = Debug /* A debug message, useful for debugging but too verbose to be turned on normally. */
  • 5 = Verbose /* A message that will be printed a lot, useful for debugging program flow and will probably impact performance. */

Some modules may not work exactly according to the log levels noted above. Very few modules actually have more than one logging level

Generating a Protocol Log


Create a batch file by copying the lines below and paste them into the notepad application, and save the file as "create_imap_log.bat". Variables MOZ_LOG and MOZ_LOG_file must not contain quotation marks.

set MOZ_LOG=IMAP:5,timestamp
set MOZ_LOG_FILE=%USERPROFILE%\Desktop\imap.log
"%ProgramFiles(x86)%\Mozilla Thunderbird\thunderbird.exe"
  • To log a different module, replace "IMAP" with e.g. "MIME" In the above instructions
  • XP and Vista users should specify %ProgramFiles% instead of %ProgramFiles(x86)% (which is for Windows 7) - assuming Thunderbird was installed to it's default location.
  • On versions with User Account Control such as Vista and Windows 7, the batch file must be run with administrator privileges. Right click on the batch file and select "Run as administrator". Otherwise the log file will not be created and no UAC warnings will be generated.

Now run the batch file. The example puts the log file on your desktop:

You can set up the batch file to be run using of these methods: double click the batch file, create a shortcut, add it to start menu, from a command window prompt, or from the start>run dialog.

Logging commands can also typed directly in the command prompt instead of running a batch file. On Windows 2000, XP, 2003 Server: Start>Programs>Accessories>Command Prompt. On later windows versions, you may type "cmd" and press enter in the launch dialog of the Start button.

Mac OS X

To generate an IMAP protocol log, create a text file that contains the desired commands in a text editor such as BBEdit:

export MOZ_LOG=IMAP:5,timestamp
export MOZ_LOG_FILE=$HOME/imap.log
/Applications/ &

If on 10.5 change the last line to arch -arch i386 /Applications/ &

Save this file with a filename ending in .command, add execute permission by typing "chmod a+x filename" in a Terminal window, then double-click it.

To get a log for another protocol, replace "imap" with e.g. "MIME" in the above instructions.

Alternatively, you can setup a file so that the protocol tracing will always be in effect. To do this open a Terminal window, cd into the .MacOSX directory under your login directory and create a file named environment.plist containing the following. Non-unix users can use the "pico" editor which I think is available on OS X by default:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
<plist version="1.0">

Note, line starting with "<!DOCTYPE" should be oneline all the way to "dtd", but I'm not sure if that makes a difference.


To generate an IMAP protocol log, run the following commands before running the application from the command line:

# For bash shell (the default shell on most GNU/Linux systems):
export MOZ_LOG=IMAP:5,timestamp
export MOZ_LOG_FILE=/tmp/imap.log
# For tcsh / csh (which is not as common):
setenv MOZ_LOG IMAP:5
setenv MOZ_LOG_FILE /tmp/imap.log

To get a log for another protocol, replace "IMAP" with e.g. "MIME" in the above instructions.

Missing Log File

If your log file is empty or missing, review this document again, and check for these common problems:

  • Do you have write access to the directory specified in MOZ_LOG_FILE?
  • Did you shut down the mailnews application? (the log file is buffered in memory)
  • Did you restart your mailnews application, and wipe out the log of the session you wanted to debug? (every restart wipes out the previous log)
  • If you used a batch file on Windows, is the batch file set to run with administrator privileges?
  • Do your log variables contain quotation marks or other invalid characters?
  • Are your log module names correctly CASE SENSITIVE? (i.e. camel case which is not all upper case, nor all lower case)

Reference Documents

Other Protocol Logging options within MailNews

The following modules may or may not be available in release builds, but are available in debug builds:

  1. IMAPAutoSync (before Thunderbird version 59: ImapAutoSync)
  3. IMAP_KW (for keyword (tag) processing)
  4. IMAPCache (for IMAP caching of messages in no-sync folders)
  5. Import (before Thunderbird version 59: IMPORT)
  6. MAPI
  7. MAPIAddressBook
  8. Movemail
  9. AbOutlookDirectory (before Thunderbird version 59: nsAbOutlookDirectoryLog)
  10. AbOutlookDirFactory (before Thunderbird version 59: nsAbOutlookDirFactoryLog)
  11. AbWinHelper (before Thunderbird version 59: nsAbWinHelperLog)
  12. WABAddressBook
  13. negotiateauth (Mozilla core option)

Other Important MailNews logging

  • Log Gloda activity to console (Thunderbird only) Debugging Gloda
  • Calendar/Lightning logging
  • To show chat logging in the console, set PRPL_LOG=0 or the purple.debug.loglevel pref
    • Logging for OTR is controlled by the chat.otr.trace boolean pref

Other Useful NSPR Logging Options

The following modules may or may not be available in release builds, but are available in debug builds:

  • nsDragService

The following modules are not owned by Mail&News, but useful for problem analysis of Mail&News.

  • nsHostResolver, nsSocketTransport HTTP_Logging (DNS lookup, Socket log)
  • DOMLeak, DocumentLeak, nsDocShellLeak Leak Gauge (Internal load of mail can be traced)
  • pipnss - S/MIME (nsCMSMessage) debugging

Logging Tools

  • Log Parsing - Logs can be difficult to parse because of their size. Andrew Sutherland has written a parsing script in Python for analyzing these logs. The script may need to be tweaked to suit your needs. There is more information at this bug comment.

Enhancement Ideas

Logging prior to Thunderbird 55.0a1 / SeaMonkey 2.52a1

Around April 5, 2017, via bug 1222244 and blockers of bug 1219461, changes were merged to the Mozilla trunk which impacted logging functionality. Prior to these changes, the variable names used to configure logging were NSPR_LOG_MODULES and NSPR_LOG_FILE rather than MOZ_LOG and MOZ_LOG_FILE. If you are working with an older version, use the old variable names.

In addition, some log module names changed. The old names are documented below, but will eventually be removed (along with this section) when enough time has past that it is no longer necessary for most people to debug older versions of the applications. Of course, the obsolete documentation will remain accessible in the history of this page.

Note that log module names are CASE SENSITIVE.