Console service

The Console Service interface supports logging runtime messages from any source. Messages can then be displayed to the user with the Error Console, logged to disk, etc.

Basic logging

3 main objects are used for logging high-level messages in Mozilla:

• A console message nsIConsoleMessage: it contains the string message.
• A console listener nsIConsoleListener: allow the rendering of console messages
• A console service nsIConsoleService: let components log their messages and register the listeners who going to receive message notification

Component developer point of view

The following example shows how to log a simple string. You can view the log in Firefox with the Error Console. Your message will appear with the info icon.

Example 1. Sample string logging (C++)

nsCOMPtr<nsIConsoleService> aConsoleService =
    do_GetService( "@mozilla.org/consoleservice;1" );
aConsoleService->LogStringMessage(
    NS_LITERAL_STRING( "a logging message" ).get());

Example 2. Sample string logging (JavaScript)

var aConsoleService = Components.classes["@mozilla.org/consoleservice;1"].
     getService(Components.interfaces.nsIConsoleService);
aConsoleService.logStringMessage("a logging message");

Application developer point of view

To see the logged message, you can either open the Firefox Error Console or implement your own nsIConsoleListener.

Basically, the only method you need to implement is observe. You then register your listener in the nsConsoleService using the registerListener method.

Each time the logMessage method is called, your observe method will be called. Depending on your choice you can show the message in the user interface, write it on a disk, or send it to a log server.

Example 3. Simple Listener

var theConsoleListener = {
    observe:function( aMessage ) {
	dump("Log : " + aMessage.message);
    },
    QueryInterface: function (iid) {
	if (!iid.equals(Components.interfaces.nsIConsoleListener) &&
            !iid.equals(Components.interfaces.nsISupports)) {
		throw Components.results.NS_ERROR_NO_INTERFACE;
	    }
        return this;
    }
};
function onLoad()
{
    var aConsoleService = Components.classes["@mozilla.org/consoleservice;1"]
        .getService(Components.interfaces.nsIConsoleService);
    aConsoleService.registerListener(theConsoleListener);
}

More fun with nsIConsoleMessage

A simple implementation of nsIConsoleMessage is handle by nsConsoleMessage; it is used by the logStringMessage method.

Depending on your specific problem, you may need a more specific class. You can implement nsIConsoleMessage, adding new attributes and methods. You must implement the message attribute in order to use nsIConsoleListener.

We may imagine a console listener that is able to email to QA dept. when a specific problem occur.

Logging Messages

The console service should be used to log any message that might be of concern to a user or UI/component developer. The console service currently gets messages from XUL and content JavaScript, XPI JavaScript, and JS Components. Other candidates are Prefs, the XML parser and XPConnect. I intend for the error list to be filterable from the JavaScript UI, so be promiscuous with what you log.

To log a message, call LogStringMessage on the service. If you want to associate more information than just a string with your message, make an XPCOM object that's QIable to nsIConsoleMessage and call LogMessage - JavaScript errors currently log instances of nsIScriptError. Console listeners can then attempt to QI from nsIConsoleMessage to richer message types that they know about. An example of logging a message is the JavaScript Component loader.

Thread safety

The console service is intended to be thread-safe; you should be able to log messages to the service from any thread. Listeners registered with the service are proxied when they are registered. When a new message is logged, each listener will be notified (asynchronously) on the thread from which it was originally registered. (For this reason, each listener must be registered on a thread with an event queue.)

Retiring Old Messages

In order to prevent denial of service by a page that generates an unbounded number of errors, the console service maintains a LIFO circular buffer of messages, and begins retiring old messages once the message limit is reached.

The Error Console

One client of the console service is the Firefox Error Console. (Tools->Error Console) The Error Console polls the console service for messages that have been logged so far and registers itself with the service as a listener for new messages. The console service itself doesn't depend on JavaScript. Everything in the console service is scriptable, and the Error Console window is implemented in pure XUL/JS.

Thanks to Martijn Pieters, we have a command line handler for the Error Console. To start up with the Error Console, use the -jsconsole argument.