1 .. title:: MochiKit.Logging - we're all tired of alert()
6 MochiKit.Logging - we're all tired of alert()
14 log("INFO messages are so boring");
15 logDebug("DEBUG messages are even worse");
16 log("good thing I can pass", objects, "conveniently");
22 MochiKit.Logging steals some ideas from Python's logging module [1]_,
23 but completely forgot about the Java [2]_ inspiration. This is a KISS
24 module for logging that provides enough flexibility to do just about
25 anything via listeners, but without all the cruft.
31 - :mochiref:`MochiKit.Base`
37 Native Console Logging
38 ----------------------
40 As of MochiKit 1.3, the default logger will log all messages to your
41 browser's native console. This is currently supported in Safari, Opera
42 9, and Firefox when the `FireBug`_ extension is installed. MochiKit
43 1.4 adds support for the relevant APIs for Internet Explorer (the
44 Debugger and the Atlas framework, see `here`__).
46 .. __: http://www.nikhilk.net/Entry.aspx?id=93
47 .. _`FireBug`: http://www.joehewitt.com/software/firebug/
49 To disable this behavior::
51 MochiKit.Logging.logger.useNativeConsole = false;
54 Bookmarklet Based Debugging
55 ---------------------------
57 JavaScript is at a serious disadvantage without a standard console for
58 "print" statements. Everything else has one. The closest thing that
59 you get in a browser environment is the ``alert`` function, which is
62 This leaves you with one reasonable solution: do your logging in the
63 page somehow. The problem here is that you don't want to clutter the
64 page with debugging tools. The solution to that problem is what we
65 call BBD, or Bookmarklet Based Debugging [3]_.
67 Simply create a bookmarklet for
68 `javascript:MochiKit.Logging.logger.debuggingBookmarklet()`__, and
69 whack it whenever you want to see what's in the logger. Of course,
70 this means you must drink the MochiKit.Logging kool-aid. It's tangy
71 and sweet, don't worry.
73 .. __: javascript:MochiKit.Logging.logger.debuggingBookmarklet()
75 Currently this is an ugly ``alert``, but we'll have something spiffy
76 Real Soon Now, and when we do, you only have to upgrade
77 MochiKit.Logging, not your bookmarklet!
86 :mochidef:`LogMessage(num, level, info)`:
91 Identifier for the log message
94 Level of the log message (``"INFO"``, ``"WARN"``,
98 All other arguments passed to log function as an ``Array``
101 ``Date`` object timestamping the log message
104 Available in MochiKit 1.3.1+
107 :mochidef:`Logger([maxSize])`:
109 A basic logger object that has a buffer of recent messages plus a
110 listener dispatch mechanism for "real-time" logging of important
113 ``maxSize`` is the maximum number of entries in the log. If
114 ``maxSize >= 0``, then the log will not buffer more than that many
115 messages. So if you don't like logging at all, be sure to pass
118 There is a default logger available named "logger", and several of
119 its methods are also global functions:
121 ``logger.log`` -> ``log``
122 ``logger.debug`` -> ``logDebug``
123 ``logger.warning`` -> ``logWarning``
124 ``logger.error`` -> ``logError``
125 ``logger.fatal`` -> ``logFatal``
128 Available in MochiKit 1.3.1+
131 :mochidef:`Logger.prototype.addListener(ident, filter, listener)`:
133 Add a listener for log messages.
135 ``ident`` is a unique identifier that may be used to remove the
138 ``filter`` can be one of the following:
141 ``listener(msg)`` will be called for every log message
145 :mochiref:`logLevelAtLeast(filter)` will be used as the
146 function (see below).
149 ``filter(msg)`` will be called for every msg, if it
150 returns true then ``listener(msg)`` will be called.
152 ``listener`` is a function that takes one argument, a log
153 message. A log message is an object (:mochiref:`LogMessage`
154 instance) that has at least these properties:
157 A counter that uniquely identifies a log message
161 A string or number representing the log level. If string,
162 you may want to use ``LogLevel[level]`` for comparison.
165 An Array of objects passed as additional arguments to the
169 Available in MochiKit 1.3.1+
172 :mochidef:`Logger.prototype.baseLog(level, message[, ...])`:
174 The base functionality behind all of the log functions. The first
175 argument is the log level as a string or number, and all other
176 arguments are used as the info list.
178 This function is available partially applied as:
180 ============== =========
185 Logger.warning 'WARNING'
186 ============== =========
188 For the default logger, these are also available as global
189 functions, see the :mochiref:`Logger` constructor documentation
193 Available in MochiKit 1.3.1+
196 :mochidef:`Logger.prototype.clear()`:
198 Clear all messages from the message buffer.
201 Available in MochiKit 1.3.1+
204 :mochidef:`Logger.prototype.debuggingBookmarklet()`:
206 Display the contents of the logger in a useful way for browsers.
208 Currently, if :mochiref:`MochiKit.LoggingPane` is loaded, then a
209 pop-up :mochiref:`MochiKit.LoggingPane.LoggingPane` will be
210 used. Otherwise, it will be an alert with
211 :mochiref:`Logger.prototype.getMessageText()`.
214 Available in MochiKit 1.3.1+
217 :mochidef:`Logger.prototype.dispatchListeners(msg)`:
219 Dispatch a log message to all listeners.
222 Available in MochiKit 1.3.1+
225 :mochidef:`Logger.prototype.getMessages(howMany)`:
227 Return a list of up to ``howMany`` messages from the message
231 Available in MochiKit 1.3.1+
234 :mochidef:`Logger.prototype.getMessageText(howMany)`:
236 Get a string representing up to the last ``howMany`` messages in
237 the message buffer. The default is ``30``.
239 The message looks like this::
241 LAST {messages.length} MESSAGES:
242 [{msg.num}] {msg.level}: {m.info.join(' ')}
243 [{msg.num}] {msg.level}: {m.info.join(' ')}
246 If you want some other format, use
247 :mochiref:`Logger.prototype.getMessages` and do it yourself.
250 Available in MochiKit 1.3.1+
253 :mochidef:`Logger.prototype.removeListener(ident)`:
255 Remove a listener using the ident given to
256 :mochiref:`Logger.prototype.addListener`
259 Available in MochiKit 1.3.1+
265 :mochidef:`alertListener(msg)`:
267 Ultra-obnoxious ``alert(...)`` listener
270 Available in MochiKit 1.3.1+
273 :mochidef:`log(message[, info[, ...]])`:
275 Log an INFO message to the default logger
278 Available in MochiKit 1.3.1+
281 :mochidef:`logDebug(message[, info[, ...]])`:
283 Log a DEBUG message to the default logger
286 Available in MochiKit 1.3.1+
289 :mochidef:`logError(message[, info[, ...]])`:
291 Log an ERROR message to the default logger
294 Available in MochiKit 1.3.1+
297 :mochidef:`logFatal(message[, info[, ...]])`:
299 Log a FATAL message to the default logger
302 Available in MochiKit 1.3.1+
305 :mochidef:`logLevelAtLeast(minLevel)`:
307 Return a function that will match log messages whose level is at
311 Available in MochiKit 1.3.1+
314 :mochidef:`logWarning(message[, info[, ...]])`:
316 Log a WARNING message to the default logger
319 Available in MochiKit 1.3.1+
325 .. [1] Python's logging module: http://docs.python.org/lib/module-logging.html
326 .. [2] PEP 282, where they admit all of the Java influence: http://www.python.org/peps/pep-0282.html
327 .. [3] Original Bookmarklet Based Debugging blather: http://bob.pythonmac.org/archives/2005/07/03/bookmarklet-based-debugging/
333 - Bob Ippolito <bob@redivi.com>
339 Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
340 dual-licensed free software; you can redistribute it and/or modify it
341 under the terms of the `MIT License`_ or the `Academic Free License
344 .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
345 .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php