MailNews:Logging

<< Back to MailNews:Home Page

Logs provide data to help developers and triagers understand what is causing an issue. Please provide a log file when requested. If you have difficulty or questions, please ask for help.

Introduction

Logging in recent years has evolved regarding:

• how logging is enabled - possibilities include command line (original method), and Thunderbird preferences (newer method)
• location of log data - possibilities include logging to a file (original method), and logging to the Error Console (alternative method)

Also, we have two types of logging:

• Thunderbird logging, for calendar, chat, gloda indexing and search, ldap, nntp (news), pop, and smtp (sending mail)
• Gecko logging, which uses case sensitive module names, such as IMAP and IMAPAutoSync

Thunderbird Logging

This is the modern method, where logging is specified by setting a preference in Thunderbird.

Unless otherwise specified, logging output goes to the Error Console, at Tools > Developer > Error Console or use the hotkey Control+Shift+J (Command+Shift+J on macOS).

Thunderbird Logging Types

Log settings of type string are Case Sensitive. For example, use All, not ALL.

• Calendar - set both calendar.debug.log and calendar.debug.log.verbose to true, and reload calendar pane. Reference: Calendar/Calendar logging
• Chat - purple.debug.loglevel set to [1]
  • 0 Show all libpurple messages (PURPLE_DEBUG_ALL)
  • 1 Very verbose (PURPLE_DEBUG_MISC)
  • 2 Verbose (PURPLE_DEBUG_INFO)
  • 3 Show warnings (PURPLE_DEBUG_WARNING)
  • 4 Show errors (PURPLE_DEBUG_ERROR)
  • 5 Show only fatal errors (PURPLE_DEBUG_FATAL)
• Chat Off-The-Record (OTR) protocol for exchanging encrypted chat messages - chat.otr.trace boolean preference
• Gloda Indexing (global search) activity to Error Console
• imap (not available in version 115) - mailnews.imap.loglevel string, set to All, but only if you have set mailnews.imap.jsmodule=true for Beta and Daily channel builds only.
• ldap - mailnews.ldap.loglevel, string, set to All
• NNTP - mailnews.nntp.loglevel, string, set to All
• OpenPGP/e2ee - logging is described at OpenPGP Debugging
• pop3 - mailnews.pop3.loglevel, string, set to All
• smtp - mailnews.smtp.loglevel, string, set to All

Setting a Preference

To configure logging via a Thunderbird Preference, you must create a hidden Thunderbird preference, not an environment variable. In Thunderbird :

1. do Settings > General
2. in the search field type config editor
3. click Config Editor in the search results
4. in the search field paste or type the preference name, for example mailnews.pop3.loglevel
5. if you are presented with choices of Boolean, Number, String
   1. choose Boolean for true or false settings, otherwise choose String
   2. click the + (plus sign) to add the preference
6. change the preferences' value to the desired logging value
   • for string preferences click the pencil icon, change the value, then click the check mark
   • for boolean preferences click the double headed arror to switch between true and false

Logging is permanent until you reset or delete a preference (by clicking the trash can).

It is not necessary to restart Thunderbird - logging starts immediately.

You can view the output at Tools > Developer > Error Console. To expose timestamp, click the gear icon in top-right of the Error Console, turn on "Show Timestamps".

Gecko Logging

Gecko logging using module names is the classic method of getting log data. Gecko logging may be enabled via preferences (not discussed in this document), or command line, which is discussed below.

Thunderbird gets its module logging capabilities from Firefox core, also known as Gecko. Gecko logging capabilities are thoroughly documented in this excellent reference, including module names.

Thunderbird Module Names

All names are CASE SENSITIVE.

1. AbOutlookDirectory (before Thunderbird version 59: nsAbOutlookDirectoryLog)
2. AbWinHelper (before Thunderbird version 59: nsAbWinHelperLog)
3. BayesianFilter
4. CMS (for S/MIME)
5. Filters
6. IMAP
7. IMAP_CS (for CONDSTORE)
8. IMAP_KW (for keyword (tag) processing)
9. IMAPAutoSync (before Thunderbird version 59: ImapAutoSync)
10. IMAPCache (for IMAP caching of messages in no-sync folders)
11. IMAPOffline (before Thunderbird version 59: IMAPOFFLINE)
12. Import (before Thunderbird version 59: IMPORT)
13. ldap (After Thunderbird 90 use Thunderbird logging)
14. Mailbox (before Thunderbird version 59: MAILBOX)
15. MailDirStore
16. MAPI
17. MAPIAddressBook
18. MIME
19. MsgBiff
20. MsgCompose (before Thunderbird version 59: msgcompose)
21. MsgCopyService (3.3a4 nightly builds starting 5/2/2011)
22. MsgDB (level 1=opens/closes, level 5 lists open db's on close, number of msg hdrs in use) (before Thunderbird version 59: MSGDB)
23. MsgPurge
24. NNTP (After Thunderbird 95 use Thunderbird logging)
25. pop3 (After Thunderbird 98 use Thunderbird logging)
26. smtp (After Thunderbird 90 use "Thunderbird logging)

Notes:

• The current, full list of Thunderbird module names is seen in this searchfox query.
• Gecko modules potentially useful to Thunderbird users:
  • nsHostResolver (for DNS)
  • GetAddrInfo (for DNS)
  • nsSocketTransport (basic networking)
  • negotiateauth (authentication)
• Version 59 bug 1353919 changed these options to be mixed case. The old, inconsistent case options are in parenthesis above.
• Deprecated:
  • Movemail
  • AbOutlookDirFactory (before Thunderbird version 59: nsAbOutlookDirFactoryLog)
  • WABAddressBook

Environment Variables to set

NOTE - do not use this section for ldap, nntp, pop3 and smtp, which are configured per Thunderbird logging.

Two variables must be set, MOZ_LOG and MOZ_LOG_FILE as local environment variables in a batch file/script (described below) or on a command line. (using global system environment variables is not recommended)

MOZ_LOG_FILE

MOZ_LOG_FILE is the path and file name to the log file. An extension of .moz_log will be added to the file name (since Thunderbird 70). If MOZ_LOG_FILE is not set, then the output will be logged to the console/terminal (stdout) where the application was launched.

Example: set MOZ_LOG_FILE=thunderbird-log-file

Note:

• The log file is written over every time you re-launch the application.
• You must have write access to the directory of the log file. The user's desktop directory or system temp directory are often a good choices.
• If you run multiple applications at the same time, such as Firefox and Thunderbird, then might both write to the log file and possibly wipe out the other's log entries. Workarounds:
  • Run only one application at a time
  • Use the append option
  • Force logging to the console by setting MOZ_LOG_FILE to null, MOZ_LOG_FILE=.

MOZ_LOG

MOZ_LOG syntax is a list of terms, separated by commas. There are two types of terms:

• A CASE SENSITIVE module name and its log level, separated by a colon (:), such as example_module:5 to enable the module example_module at logging level 5 (verbose).
• Optional special strings (switches) to configure the logging behaviour. Some configuration switches take an integer parameter, in which case the integer is separated from the string by a colon (:). Most switches only apply in a specific output context. Full documentation at [2].

Example module and loglevel: "IMAP:4,IMAPAutoSync:5,timestamp"

,timestamp adds a timestamp to all log lines - generally recommended, and required for all timeouts and issues which need to be correlated to an action at a given time of day

Logging Level

NOTE - do not use this section for ldap, nntp, pop3 and smtp, which are configured per Thunderbird logging.

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. Progammers should not use this directly in code. */
• 1 = Error /* An error occurred. Also generally something a programmer would consider asserting in a debug build. */
• 2 = Warning /* A warning often indicates an unexpected state. */
• 3 = Info /* An informational message, which often indicates the current program state. */
• 4 = Debug /* A debug message, which is 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. */ Verbose is not recommended for IMAP.

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 Gecko Log

NOTE - do not use this section for ldap, nntp, pop3 and smtp, which are configured per Thunderbird logging.

For Gecko logging, use module names.

Windows

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

set MOZ_LOG=moduleName:5,timestamp
set MOZ_LOG_FILE=%USERPROFILE%\Desktop\log_file
"%ProgramFiles(x86)%\Mozilla Thunderbird\thunderbird.exe"

• On versions with User Account Control (UAC), 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.
• 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.

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 log, create a text file that contains the desired commands in a text editor such as BBEdit:

#!/bin/sh
export MOZ_LOG=moduleName:5,timestamp
export MOZ_LOG_FILE=$HOME/Desktop/log_file
/Applications/Thunderbird.app/Contents/MacOS/thunderbird-bin &

If on MacOS 10.5, change the last line to arch -arch i386 /Applications/Thunderbird.app/Contents/MacOS/thunderbird-bin &

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.

Alternatively, you can setup a file so that the protocol tracing will always be in effect. (Not recommended if you use both Firefox and Thunderbird) 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" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>MOZ_LOG_FILE</key>
<string>/tmp/log_file.txt</string>
<key>MOZ_LOG</key>
<string>moduleName:5,timestamp</string>
</dict>
</plist>

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

Linux/unix

Variables set for MOZ_LOG and MOZ_LOG_file must be specified in quotation marks. MOZ_LOG_FILE must be fully specified without shortcuts, such as "~/". 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="moduleName:5,timestamp"
export MOZ_LOG_FILE="/tmp/log_file"

# For tcsh / csh (which is not as common):
setenv MOZ_LOG moduleName:5,timestamp 
setenv MOZ_LOG_FILE /tmp/log_file

Missing Log File

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

• If logging ldap, nntp, pop3, or smtp, you must use Thunderbird logging, not Gecko module logging using environment variables.
• If logging imap, you must use Gecko module logging using environment variables.
• If linux, variables MOZ_LOG and MOZ_LOG_file must be in quotation marks.
• If linux, MOZ_LOG_file must be fully specified without shortcuts, such as "~/"
• Do you have write access to the directory specified in MOZ_LOG_FILE?
• Did you shut down the application? (the log file is buffered in memory until the application is closed)
• 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? (meaning mixed case, or camel case which is not all upper case, nor all lower case)

NSPR Logging Options

NSPR also has logging. Miscellaneous NSPR Reference (logging).

Enhancement Ideas

• bug 492620 - better, easier logging/diagnostics for Thunderbird [meta]
• bug 193873 - Add Mozilla logging to UI / Thunderbird:Logging_UI
• bug 697522 - precise logging of message filter runs and actions

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.