MailNews:Logging: Difference between revisions

Revision as of 15:24, 20 August 2013

Mailnews logs help developers 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 modules/protocols in both debug and release builds:

imap
ImapAutoSync
ldap
mime
msgdb (level 1=opens/closes, level 5 lists open db's on close, number of msg hdrs in use)
nntp
pop3
smtp

(Other options below)

Environment Variables to set

Two variables must set. These can be as (global/system) environment variables. Or, what we document here, as variables in a batch file/script or on the command line:

NSPR_LOG_MODULES - Module name and log level separated by colon, and multiple modules separated by comma
- Example: "imap:5"
- Example: "ldap:5,smtp:3,timestamp"
- optional ",timestamp" : timestamp is added to all log entries (as of 2009-05-13 3.0b3pre builds)
- optional ",sync" : Buffering in log writing is disabled, so latest log data can be seen by ad-hoc copy of log file
NSPR_LOG_FILE - Path to the log file
- If NSPR_LOG_FILE is not set, then the output will be logged to the console where the application was launched.

Note:

The log is written over every time you re-launch the mozilla application.
You must have write access to the directory of the log file.

Logging level

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

PR_LOG_NONE = 0, /* nothing */
PR_LOG_ALWAYS = 1, /* always printed */
PR_LOG_ERROR = 2, /* error messages */
PR_LOG_WARNING = 3, /* warning messages */
PR_LOG_DEBUG = 4, /* debug messages */
5 (recommended)

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

Windows

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".

set NSPR_LOG_MODULES=imap:5
set NSPR_LOG_FILE=%USERPROFILE%\Desktop\imap.log
"%ProgramFiles(x86)%\Mozilla Thunderbird\thunderbird.exe"

To log another protocol, replace "imap" with e.g. "smtp" or "pop3" 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:

#!/bin/sh
export NSPR_LOG_MODULES=imap:5
export NSPR_LOG_FILE=$HOME/imap.log
/Applications/Thunderbird.app/Contents/MacOS/thunderbird-bin &
if on 10.5 change the above 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.

To get a log for another protocol, replace "imap" with e.g. "smtp" or "pop3" 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" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>NSPR_LOG_FILE</key>
<string>/tmp/imaptrace.txt</string>
<key>NSPR_LOG_MODULES</key>
<string>IMAP:5</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

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 NSPR_LOG_MODULES=imap:5
export NSPR_LOG_FILE=/tmp/imap.log

# For tcsh / csh (which is not as common):
setenv NSPR_LOG_MODULES imap:5
setenv NSPR_LOG_FILE /tmp/imap.log

To get a log for another protocol, replace "imap" with e.g. "smtp" or "pop3" 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?
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?

Reference Documents

NSPR Reference (logging)

Other Protocol Logging options within MailNews

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

applemailimportlog
bayesianfilter
DockCounts (for logging issues with the mac dock unread count, 3.04 and above)
gssapi
imapoffline
import
ldapautocomplete
mapi
movemail
msgbiff
msgcompose
MsgCopyService (3.3a4 nightly builds starting 5/2/2011)
msgpurge
negotiateauth
nsaboutlookcardlog
nsaboutlookdirectorylog
nsabwinhelperlog
nswabaddressbook

Other Important MailNews logging

Log Gloda activity to console(Thunderbird only) Debugging Gloda
Calendar/Lightning logging

Other Useful NSPR Logging Options