The JavaScript console API

[2013-10-05] dev, nodejs, javascript, clientjs
(Ad, please don’t block)
In most JavaScript engines, there is a global object console with methods for logging and debugging. That object is not part of the language proper, but has become a de facto standard, since being pioneered by the Firebug debugger. Since their main purpose is debugging, the console methods will most frequently be used during development and rarely in deployed code.

This blog post gives an overview of the methods of console.

How standardized is the console API across browsers?

Firebug first provided the console API and the documentation in its wiki is the closest thing to a standard there is. Additionally, Brian Kardell and Paul Irish are working on a specification for the API, which should lead to more consistent behavior across browsers in the long term. Until then, behavior varies widely. Therefore, this blog post can only provide an overview. For details, you should consult the following documentation for various platforms: Bug in Internet Explorer 9: in that browser, the console object only exists if the developer tools were open at least once. That means that you get a ReferenceError if you refer to console and the tools weren’t open before. As a work-around, you can check whether console exists and create a dummy implementation, if it doesn’t.

Simple logging

Methods:
  • console.clear()
    Clear the console.
  • console.debug(object1, object2?, ...)
    Prefer console.log(), which does the same as this method.
  • console.error(object1, object2?, ...)
    Log the parameters to the console. In browers, the logged content may be marked by an “error” icon and/or include a stack trace or a link to the code.
  • console.exception(errorObject, object1?, ...]) [Firebug-only]
    Log object1 etc. and show an interactive stack trace.
  • console.info(object1?, object2?, ...)
    Log the parameters to the console. In browers, the logged content may be marked by an “error” icon and/or include a stack trace or a link to the code.
  • console.log(object1?, object2?, ...)
    Log the parameters to the console. If the first parameter is a printf-style format string, use it to print the remaining parameters. Example (Node.js REPL) 
        > console.log('%s', { foo: 'bar' })
    [object Object]
    > console.log('%j', { foo: 'bar' })
    {"foo":"bar"}
    The only dependable cross-platform formatting directive is %s. Node.js supports %j to format data as JSON, browsers tend to support directives that log something interactive to the console.
  • console.trace()
    Logs a stack trace (which is interactive in browsers).
  • console.warn(object1?, object2?, ...)
    Log the parameters to the console. In browers, the logged content may be marked by an “warning” icon and/or include a stack trace or a link to the code.
Support on various platforms:

ChromeFirebugFirefoxIENode.jsSafari
clear✓✓✓✓
debug✓✓✓✓✓
error✓✓✓✓✓✓
exception✓
info✓✓✓✓✓✓
log✓✓✓✓✓✓
trace✓✓✓✓✓✓
warn✓✓✓✓✓✓

exception has been typeset in italics, because it is only supported on a single platform.

Checking and counting

Methods:
  • console.assert(expr, obj?)
    If expr is false, log obj to the console and throw an exception. If it is true, do nothing.
  • console.count(label?)
    Count how many times the line with this statement is executed with this label.
Support on various platforms:

ChromeFirebugFirefoxIENode.jsSafari
assert✓✓✓✓✓
count✓✓✓✓

Formatted logging

Methods:
  • console.dir(object)
    Print a representation of the object to the console. In browsers that representation can be explored interactively (in Node.js, it can’t).
  • console.dirxml(object)
    Print the XML source tree of an HTML or XML element.
  • console.group(object1?, object2?, ...)
    Log the objects to the console and open a nested block that contains all future logged content. The block is closed by calling console.groupEnd(). The block is initially expanded, but can be collapsed.
  • console.groupCollapsed(object1?, object2?, ...)
    Works like console.group(), but the block is initially collapsed.
  • console.groupEnd()
    Close a group that has been opened by console.group() or console.groupCollapsed().
  • console.table(data, columns?)
    Print an array as a table, one element per row. The optional parameter columns specifies which properties/array indices are shown in the columns. If that parameter is missing, all property keys are used as table columns. Missing properties and array elements show up as undefined in columns. 
        var persons = [
        { firstName: 'Jane', lastName: 'Bond' },
        { firstName: 'Lars', lastName: 'Croft', age: 72 }
    ];
    // Equivalent:
    console.table(persons);
    console.table(persons, ['firstName', 'lastName', 'age']);
    The resulting table is:

    (index)firstNamelastNameage
    0"Jane""Bond"undefined
    1"Lars""Croft"72
Support on various platforms:

ChromeFirebugFirefoxIENode.jsSafari
dir✓✓✓✓✓✓
dirxml✓✓✓✓
group✓✓✓✓✓
groupCollapsed✓✓✓✓✓
groupEnd✓✓✓✓✓
table✓✓

Profiling and timing

Methods:
  • console.markTimeline(label) [Safari-only]
    The same as timeStamp().
  • console.profile(title?)
    Turn on profiling. The optional parameter title is used for the profile report.
  • console.profileEnd()
    Stop profiling and print the profile report.
  • console.time(label)
    Start a timer whose label is label.
  • console.timeEnd(label)
    Stop the timer whose label is label and print the time that has elapsed since starting it.
  • console.timeStamp(label?)
    Log a time stamp with the given label. May be logged to the console or a timeline.
Support on various platforms:

ChromeFirebugFirefoxIENode.jsSafari
markTimeline✓
profile✓✓(devtools)✓✓
profileEnd✓✓(devtools)✓✓
time✓✓✓✓✓✓
timeEnd✓✓✓✓✓✓
timeStamp✓✓

markTimeline has been typeset in italics, because it is only supported on a single platform. (devtools) means that the developer tools must be open in order for the method to work.

Acknowledgements

Two people contributed to this blog post: Matthias Reuter (@gweax) and Philipp Kyeck (@pkyeck).