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.
188.8.131.52 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:
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.
There are several special module names:
184.108.40.206 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:
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
Tips on how to debug Firefox on Windows can be found at http://www.mozilla.org/build/win32-debugging-faq.html