Hack 96. Turn on Firefox Diagnostics

Make Firefox spew out every last detail that it knows.

Firefox and its extensions are good for several different debugging or diagnostic activities, including diagnosis of web pages and debugging of chrome applications. This hack shows how to diagnose Firefox itselfat least, just a little bit. It's an outsider's view of the tools that the core Mozilla programmers have left in place, hidden for discovery and experimentation by those that are curious.

Diagnostics are a last resort when Firefox is not providing any other useful informationfor example, during the reading of proxy or preference files. The main limitation of this extra diagnostic material is that a full understanding of the output can be obtained only if you also study the Firefox source code. Nevertheless, some of the information produced is revealing in its own right.

9.7.1. Turning On Diagnostics with NSPR Logging

At the base of the Mozilla technology stack is a C library of cross-platform features called Netscape Portable Runtime (NSPR). This library includes a logging feature that allows code to be instrumented so that it reports diagnostic strings. Mozilla programmers have divided the Firefox code up into named logging modules. Strings output sent from the code using PR_LOG() can be selected for display at runtime.

The standard install of Firefox supports this logging. Up to 75 KB of output can be generated just by starting up Firefox. If the version of Firefox used is compiled with --enable-debug, over 50 times that amount can be generated. Diagnostic output is therefore quite verbose.

9.7.1.1 Turning on logging

The NSPR_LOG_MODULES environment variable controls what is logged. Set it to a comma-separated set of module specifiers. Each module specifier has the format:

name:number

where name is a known module name and number is usually a digit in the range of 0 to 4. Here's an example (for Unix shell):

NSPR_LOG_MODULES="nsHttp:4,cooke:1"
export NSPR_LOG_MODULES

On Windows, you can set such variables by going through Control PanelSystemAdvancedEnvironment Variables. Some of the module names that are useful for non-programmers are:

cache cookie JSDiagnostics ldap MCD negotiateauth nsHttp nsSharedPrefHandler 
NTLM proxy syspref

These names are magic strings buried in the code. Table 9-1 shows the meaning of the numeric digit.

Table 9-1. Logging values and their meanings

Value	Meaning
0	Don't log anything
1	Log informational messages
2	Same as 1, plus error messages
3	Same as 2, plus warning messages
4	Same as 3, plus debug and notice messages
99	Any number bigger than 4 acts the same as 4

There are several special module names:

all

Turn on logging to the specified level for all known modules.

sync

A special flag. Log strings straight away. Don't buffer them inside Firefox memory; flush them out right away. This does not cause a sync-to-disk operation and is useful if you think Firefox is going to crash or become confused.

bufsize

A special flag. Change the amount of space available for buffered-up strings. The default is 16384 bytes; make it huge if you want to reduce the effect of disk-based logging or of scrolling screen output on Firefox performance.

9.7.1.2 Viewing logged output

Two forms of output are produced: informal diagnostic messages that are controlled by the log level and delivered via printf(), and formal diagnostic strings that are controlled by the log level and delivered by the PR_LOG() logging system. These are sent to stdout and stderr, respectively. To see the output on Windows, start Firefox with the -console option:

set NSPR_LOG_MODULES=all:5
"C:\Program Files\Firefox\firefox.exe" -console

The informal strings can be captured to a file by simply redirecting the standard output:

"C:\Program Files\Firefox\firefox.exe" > stdout.log

On Unix/Linux, the formal strings can be sent to a file by redirecting standard error:

/local/install/firefox/firefox 2> stderr.log

On all platforms, setting the NSPR_LOG_FILE environment variable to a file's full pathname causes the formal strings to be written to that file.

On Windows, if NSPR_LOG_FILE is set to the special value WinDebug, the formal strings go to the Windows OutputDebugString() API. Any debug tool that knows how to register itself with Windows can capture these strings. One useful, free, and simple tool is DebugView. Get it here:

http://www.sysinternals.com/ntw2k/freeware/debugview.shtml

What you make of the diagnostic output is up to you!

9.7.2. Finding Talkback Crash Records

If you choose to install the Quality Feedback Agent when Firefox is first installed, extra diagnostics are produced in rare cases. These errors are produced only if Firefox crashes or otherwise catastrophically fails. They can be submitted (on your approval) over the Internet to the Mozilla Foundation, where a server stores and analyzes them. The primary thing they contain is a stack dump of the state of the Firefox program at the moment of crisis. You can see and query the database of crash incidents at http://talkback-public.mozilla.org.

9.7.3. Hooking Up Firefox to a Debugger

As for any compiled program, if there's enough information in the executable, you can apply a runtime debugger to the code. For Firefox, you really need a build that's compiled for debug, such as a nightly build [Hack #92] .

Here's an example of setting up a debugging session on Linux, using gdb and bash. Run Firefox and then hook gdb up to it as follows:

cd `type -P firefox`
./firefox &
gdb firefox-bin 
pid

The pid used should be that of the Firefox binary, not the Firefox wrapper script. Find it with ps -ef. Once inside gdb, stop Firefox and orient yourself as for any interactive debugging session:

gdb> break
gdb> continue
gdb> backtrace

You can then step through the code for as long as your interest is sustained.

Tips on how to debug Firefox on Windows can be found at http://www.mozilla.org/build/win32-debugging-faq.html