Console service

  • Revision slug: Console_service
  • Revision title: Console service
  • Revision id: 93862
  • Created:
  • Creator: Yoshino
  • Is current revision? No
  • Comment Formatting

Revision Content

This document duplicates parts of information from nsIConsoleService.

The {{template.Source("xpcom/base/nsIConsoleService.idl", "Console Service interface")}} supports logging runtime messages from any source. Messages can then be displayed to the user with the JavaScript Console, logged to disk, etc.

Basic logging

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

  • A console message {{template.Source("xpcom/base/nsIConsoleMessage.idl", "<code>nsIConsoleMessage</code>")}}: it contains the string message.
  • A console listener {{template.Source("xpcom/base/nsIConsoleListener.idl", "<code>nsIConsoleListener</code>")}}: allow the rendering of console messages
  • A console service {{template.Source("xpcom/base/nsIConsoleService.idl", "<code>nsIConsoleService</code>")}}: 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 {{template.Source("xpcom/base/nsIConsoleMessage.idl", "nsIConsoleMessage")}} and call LogMessage - JavaScript errors currently log instances of {{template.Source("js/src/xpconnect/idl/nsIScriptError.idl", "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 {{template.Source("js/src/xpconnect/loader/mozJSComponentLoader.cpp#197", "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.

Original Document Information

  • Author(s): Mike McCabe, David Olivari
  • Last Updated Date: May 7, 2000
  • Copyright Information: Portions of this content are © 1998–2007 by individual mozilla.org contributors; content available under a Creative Commons license | Details.
{{ wiki.languages( { "ja": "ja/Console_service" } ) }}

Revision Source

<div class="note">This document duplicates parts of information from <a href="en/NsIConsoleService">nsIConsoleService</a>.</div>
<p>The {{template.Source("xpcom/base/nsIConsoleService.idl", "Console Service interface")}} supports logging runtime messages from any source. Messages can then be displayed to the user with the JavaScript Console, logged to disk, etc.
</p>
<h3 name="Basic_logging"> Basic logging </h3>
<p>3 main objects are used for logging high-level messages in Mozilla:
</p>
<ul><li> A console message {{template.Source("xpcom/base/nsIConsoleMessage.idl", "&lt;code&gt;nsIConsoleMessage&lt;/code&gt;")}}: it contains the string message.
</li><li> A console listener {{template.Source("xpcom/base/nsIConsoleListener.idl", "&lt;code&gt;nsIConsoleListener&lt;/code&gt;")}}: allow the rendering of console messages
</li><li> A console service {{template.Source("xpcom/base/nsIConsoleService.idl", "&lt;code&gt;nsIConsoleService&lt;/code&gt;")}}: let components log their messages and register the listeners who going to receive message notification
</li></ul>
<h4 name="Component_developer_point_of_view"> Component developer point of view </h4>
<p>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.
</p><p>Example 1. Sample string logging (C++)
</p>
<pre class="eval">nsCOMPtr&lt;nsIConsoleService&gt; aConsoleService =
    do_GetService( "@mozilla.org/consoleservice;1" );

aConsoleService-&gt;LogStringMessage(
    NS_LITERAL_STRING( "a logging message" ).get());
</pre>
<p>Example 2. Sample string logging (JavaScript)
</p>
<pre class="eval">var aConsoleService = Components.classes["@mozilla.org/consoleservice;1"].
     getService(Components.interfaces.nsIConsoleService);

aConsoleService.logStringMessage("a logging message");
</pre>
<h4 name="Application_developer_point_of_view"> Application developer point of view </h4>
<p>To see the logged message, you can either open the Firefox Error Console or implement your own <code>nsIConsoleListener</code>.
</p><p>Basically, the only method you need to implement is <code>observe</code>.  You then register your listener in the <code>nsConsoleService</code> using the <code>registerListener</code> method.
</p><p>Each time the <code>logMessage</code> method is called, your <code>observe</code> 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.
</p>
<h5 name="Example_3._Simple_Listener"> Example 3. Simple Listener </h5>
<pre class="eval">var theConsoleListener =
{
    observe:function( aMessage ){
	dump("Log : " + aMessage.message);
    },
    QueryInterface: function (iid) {
	if (!iid.equals(Components.interfaces.nsIConsoleListener) &amp;&amp;
            !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);
}

</pre>
<h3 name="More_fun_with_nsIConsoleMessage"> More fun with <code>nsIConsoleMessage</code> </h3>
<p>A simple implementation of <code>nsIConsoleMessage</code> is handle by <code>nsConsoleMessage</code>; it is used by the <code>logStringMessage</code> method.
</p><p>Depending on your specific problem, you may need a more specific class. You can implement <code>nsIConsoleMessage</code>, adding new attributes and methods. You must implement the <i><code>message</code></i> attribute in order to use <code>nsIConsoleListener</code>.
</p><p>We may imagine a console listener that is able to email to QA dept. when a specific problem occur.
</p>
<h3 name="Logging_Messages"> Logging Messages </h3>
<p>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.
</p><p>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 {{template.Source("xpcom/base/nsIConsoleMessage.idl", "nsIConsoleMessage")}} and call LogMessage - JavaScript errors currently log instances of {{template.Source("js/src/xpconnect/idl/nsIScriptError.idl", "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 {{template.Source("js/src/xpconnect/loader/mozJSComponentLoader.cpp#197", "JavaScript Component loader")}}.
</p>
<h3 name="Thread_safety"> Thread safety </h3>
<p>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.)
</p>
<h3 name="Retiring_Old_Messages"> Retiring Old Messages </h3>
<p>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.
</p>
<h3 name="The_Error_Console"> The Error Console </h3>
<p>One client of the console service is the Firefox Error Console. (Tools-&gt;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.
</p><p>Thanks to <a class="external" href="mailto:mj@digicool.com">Martijn Pieters</a>, we have a command line handler for the Error Console. To start up with the Error Console, use the <code>-jsconsole</code> argument.
</p>
<div class="originaldocinfo">
<h2 name="Original_Document_Information"> Original Document Information </h2>
<ul><li> Author(s): <a class="external" href="mailto:mike+mozilla@meer.net">Mike McCabe</a>, <a class="external" href="mailto:dolivari@eprocess.fr">David Olivari</a>
</li><li> Last Updated Date: May 7, 2000
</li><li> Copyright Information: Portions of this content are © 1998–2007 by individual mozilla.org contributors; content available under a Creative Commons license | <a class="external" href="http://www.mozilla.org/foundation/licensing/website-content.html">Details</a>.
</li></ul>
</div>
<div class="noinclude">
</div>
{{ wiki.languages( { "ja": "ja/Console_service" } ) }}
Revert to this revision