Currently, Thunderbird tends to eat a lot of exceptions. Some make it to the error console, most don't. There are deep fixes to the platform needed (e.g. bug 493414), but in the meantime, it would be helpful to be able to get useful output on stderr about exceptions, events and pretty-printed objects.
There are a couple of tools available for viewing exceptions: the errUtils module and the log4moz extension.
errUtils New in Thunderbird 3
The errUtils module contains a set of helper methods for debugging, such as logging exception objects, dumping DOM nodes, Events, and generic object dumps.
Basic use case
The basic use case is:
Components.utils.import("resource://gre/modules/errUtils.js"); ... try { ... do stuff that might throw an exception } catch (e) { logException(e, true); // second arg is whether to rethrow } ...which results in the following on the dump output:
-- EXCEPTION START -- + message (string) 'a is not defined' + fileName (string) 'chrome://messenger/content/folderDisplay.js' + lineNumber (number) 483 + stack (string) 428 chars + name (string) 'ReferenceError' * -- EXCEPTION END -- <top> FolderDisplayWidget_show@chrome://messenger/content/folderDisplay.js:522 FolderPaneSelectionChange@chrome://messenger/content/commandglue.js:352 onselect@chrome://messenger/content/messenger.xul:1 [anonymous]@null:0 onxblmousedown@chrome://global/content/bindings/tree.xml:975
Event handler
In an event handler, you can:
logEvent(event);
...and it will output stuff like:
-EVENT -------------------------- type: click eventPhase: 3 target: [object HTMLSpanElement] target.nodeName: span target.id: null currentTarget: [object HTMLDivElement] currentTarget.nodeName: div currentTarget.id: query-explanation originalTarget: [object HTMLSpanElement] originalTarget.nodeName: span originalTarget.id: null bubbles: true cancelable: true detail: 1 button: 0 isChar: false shiftKey: false altKey: false ctrlKey: false metaKey: false clientX: 385 clientY: 30 screenX: 488 screenY: 156 layerX: 57 layerY: 30 isTrusted: true timeStamp: 2080434436 -------------------------------------
JavaScript object
If faced with a generic JavaScript object, you can get detailed debugging output as follows. For example, given:
let x = {'foo': 123, 'bar': {'sub-key': 1, 'sub-key-2': 'tomato'}}; Do:
logObject(x, 'x');This yields:
Dumping Object: x + foo (number) 123 + bar (object) [object Object] | + sub-key (number) 1 | + sub-key-2 (string) 'tomato' | * *
DOM elements
If faced with a DOM element, you can print it out. For example:
logElement(document.getElementById('query-explanation', 'query-explanation'))
...yields:
<div
id='query-explanation'
>
<span
class='explanation-fulltext-label'
>
<#text
Searching for'
</span>
<span
class='explanation-fulltext-term'
>
<#text
gloda'
</span>
</div>
log4moz
The Mozilla Labs log4moz interface is a partial implementation of Apache's log4* project (for example, log4j). To use it, create one or more appenders while initializing your add-on, and create loggers in the places where you have logging messages to emit. Minimum log levels to allow you to customize your logging output without changing any code.
Protocol logging
Activity regarding specific protocols (such as IMAP, SMTP, etc) can be logged by setting environment variables that specify the protocol and degree of verbosity in the log. This is explained on the MailNews Logging page on the Mozilla wiki.