MailNews:Logging

From MozillaWiki
Jump to navigation Jump to search

<< Back to MailNews:Home Page

MailNews logging is activated by setting two environment variables before running a MailNews application.

Main Logging options within MailNews

The following modules/protocols may be logged within MailNews applications (SeaMonkey/Thunderbird) in both debug and release builds:

  • mime
  • imap
  • nntp
  • smtp
  • pop3
  • ldap
  • ImapAutoSync
  • MSGDB (level 1 is just opens and closes, level 5 lists the open db's on every db close plus number of msg hdrs in use)
  • DockCounts (for logging issues with the mac dock unread count, 3.04 and above)

(Other options below)

  • MsgCopyService (3.3a4 nightly builds starting 5/2/2011)

Environment Variables to set

Two environment variables must set:

  1. NSPR_LOG_MODULES - Module name and level separated by colon
    • Example: "imap:5"
    • Example: "ldap:5,smtp:3,timestamp"
    • adding optional ",timestamp" time stamps all log entries (as of 2009-05-13 3.0b3pre builds)

  2. 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 example above specifies the level of logging to be used. A lower number reduces the amount of information that is logged to the file:

  • 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 */

Use "5" unless requested otherwise. Some modules may not work exactly according to the log levels noted above. Very few of the modules actually have different logging levels

Generating a Protocol Log

Windows

There are various ways to set the environment variables for protocol logging. One is to create a batch file e.g. "create_imap_log.bat" with the following lines: 

set NSPR_LOG_MODULES=imap:5
set NSPR_LOG_FILE=%APPDATA%\imap.log
"C:\Program Files\Mozilla Thunderbird\thunderbird.exe"

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

When you want to run Thunderbird/SeaMonkey with logging, just run the batch file. You can double click it, create a shortcut to it, move it into your start menu, or run it from a command prompt or the start>run dialog.

On windows versions with User Account Control, the batch file must be run with administrator privileges. If ran without, The log file will not be created and no UAC warnings will be generated. Right click on the batch file and select "Run as administrator".

The above commands can also be executed directly in the command prompt. 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=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

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
  • gssapi
  • imapoffline
  • import
  • ldapautocomplete
  • mapi
  • movemail
  • msgbiff
  • MsgCopyService
  • msgcompose
  • msgpurge
  • negotiateauth
  • nsaboutlookcardlog
  • nsaboutlookdirectorylog
  • nsabwinhelperlog
  • nswabaddressbook

Calendar logging is documented here

Other Important MailNews logging

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)

Log Parsing Tools

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.

TBTracer addon on amo has been made available by Thundersomething author "derdoc" as of recently TBTracer

Retrieved from "https://wiki.allizom.org/index.php?title=MailNews:Logging&oldid=391449"