Guide to Logging

The console API allows developers to output information to the web console of the browser.

Logging API

The log module in commonplace allows the developer to achieve the same result, but organizes and archives logged information and actions to an in-memory (or persistent, depending on the API) log store. This document is intended to describe the log module's API and it's appropriate usage.

Using log

To use the logging module, import it in this manner:

define('module_name', ['log'], function(log) {
    var console = log('module_name');
    // ...
});

module_name is the name of your module, though you can pass an abbreviated name to log (e.g.: requests passes req).

The console object can then be treated in the same manner as the window.console object.

Methods

log()

log(message[, message[, ...]])

Maps to console.log.

Uses:

• When a notable action takes place
• When new information is available
• When an action takes place that happens only under certain conditions

console.log should NOT be used

• inside tight loops or when processing batches of data
• in frequently called functions, or regularly in functions that are called on an interval
• to indicate an error or some kind of failure

warn()

warn(message[, message[, ...]])

Maps to console.warn.

Uses:

• When unexpected but safe actions occur
• When errors occur but can be recovered from
• When data is malformed but can be corrected

console.warn should NOT be used

• to call attention to output that is not a failure or problematic (use console.log instead with tagged)
• to indicate an unrecoverable error (use console.error instead)

error()

error(message[, message[, ...]])

Maps to console.error

Uses:

• When unexpected actions occur that will negatively impact the user or the application state
• When data is malformed or unavailable and cannot be recovered
• When errors take place that cannot be handled elsewhere without further impacting application state

console.error should NOT be used

• on trivial errors or errors that do not affect output (use console.warn instead)

group()

group(message[, message[, ...]])

Maps to console.group

Uses:

• When a series of identical actions are going to be performed that will each produce output. E.g.: when casting multiple objects to the model cache
• When multiple similar events are about to take place in sequence and are generally not of interest. E.g.: when parsing input or performing URL routing

group does not store additional information in the internal log module. It will not be visible in archived logs.

groupEnd()

groupEnd()

Maps to console.groupEnd

Uses:

• When a group has ended, use this to display the group in the console
• When the group being closed is important but represents a single discrete action which can (or should) be hidden during debugging

groupCollapsed()

groupCollapsed()

Maps to console.groupCollapsed

Uses:

• When a group has ended, use this to show the group in the console in a default collapsed state
• When the group being closed is not critical to debugging

tagged()

tagged(tag)

Returns a new log object with the tag tag.

// These are functionally equivalent.
var logger = log('module', 'tag');
var tagged_logger = log('module').tagged('tag');

If the current log object already has a tag, it will be extended with another:

var tagged_logger = log('module', 'first').tagged('second');
tagged_logger.log('foo');
// [module][first][second] foo

API

log()

log(module[, tag[, onlog]])

Returns a new logging instance which include the methods listed above. module is the name of the module that intends to write logs.

If tag is specified, that tag will be prepended to the log message:

var tagged_logger = log('module', 'tag');
tagged_logger.log('foo');
// [module] [tag] foo

If onlog is specified, it will be called whenever any message is to be written to the console. It will be called with a single argument: an array containing the arguments passed to the method that was called to log. I.e.:

var console = log('module', null, function(data) {
    // data == ['foo', 'bar']
});
console.log('foo', 'bar');

log.logs

Returns an object which includes all logs written to the logging module.

var console = log('foo');
console.log('Hello');
console.warn('Goodbye');

>>> log.logs
{
  'foo': [
    ['[foo] Hello'],
    ['[foo] Gooodbye']
  ]
}

log.all

Contains a single list of all logs written to the logging module.

log('foo').log('Hello');
log('bar').log('Goodbye');

>>> log.all
[
  ['[foo] Hello'],
  ['[bar] Gooodbye']
]

log.get_recent()

log.get_recent(count[, type])

Returns the count most recent logs. If type is specified, returns the count most recent logs for the type module.

log('foo').log(1);
log('foo').log(2);
log('foo').log(3);
log('bar').log(4);
log('bar').log(5);

>>> log.get_recent(4)
[
  ['[foo] 2'],
  ['[foo] 3'],
  ['[bar] 4'],
  ['[bar] 5']
]

>>> log.get_recent(2, 'foo')
[
  ['[foo] 2'],
  ['[foo] 3']
]

log.unmention()

log.unmention(string)

Adds string to a list of strings which are censored in logs. The exact string and its URL-encoded counterpart are both added to the list of censored strings.

log.unmention('zip');

log('foo').log('Unzip the file to your hard disk');
// Logs `[foo] Un--- the file to your hard disk`

>>> log.all_logs
[
  ['[foo] Un--- the file to your hard disk']
]

log.unmentionables

Contains a list of strings (and their URL-encoded counterparts) which are censored in logs.

log.filter()

log.filter(string)

Returns the censored version of string. If string is not a JS string, it is returned unmodified.

log.unmention('foo')
log.filter('abc foo bar');
// Returns 'abc --- bar'

log.persistent()

log.persistent(module_name)

Identical in interface and usage to log('module_name'). Returns a console API object.

This API method, however, persists logs after the page has unloaded using the storage module.

log.persistent.all

Identical to log.all, except returns only persistent log archives.

This is the only way to access archived persistent logs from previous browser sessions. Only newly logged messages logged with log.persistent will appear in log.all.