The JavaScript console API

By -
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).

Comments

Post a Comment

Popular posts from this blog

Steve Lopez and the Importance of Newspapers

By -
Image
It has been one year since I cancelled my subscriptions to The New York Times and the Los Angeles Times . In that time, I continued to read both publications online. My assessment of this experiment is that reading newspapers and journalism online is vastly inferior to the hard copy thrown on my porch each morning. So I restarted my subscription to the Los Angeles Times and I have made it a point to buy The New York Times as often as I pass one of those coin boxes or my local news stand. The catalyst for this re-evaluation resulted from catching the film, The Soloist on cable last week. I liked the movie, although the scenes I found most interesting were the ones that showed columnist Steve Lopez at work. I realized the book was sitting in my “to-read” stack, so I pulled it and began reading. The book, as I expected, is better than the film. Lopez clearly addresses the revolution occurring in journalism, and worries about his future with the paper even as he researches and writes...
Keep reading

Ideas for fixing unconnected computing

By -
I traveled quite a bit recently and got exposed to a negative aspect of current technology: Things work well if you have a solid internet connection with no traffic limits and are plugged into a power outlet. Otherwise, things do not work well at all. This blog post describes the problems that arise and suggests solutions. Managing data traffic Cell phones are quite good at conserving traffic, laptops much less so. This becomes a problem when your laptop has a mobile connection (e.g., via tethering or in a hotel with data caps). I once accidentally started iTunes in such a situation and immediately used up my daily allowance of traffic. Similarly, mobile email is frugal with traffic (only the current folder is updated, attachments are only downloaded on demand, etc.), desktop email is usually not. How can this be handled better? I’d like to see three traffic modes for all operating systems: “full”, “restricted”, “minimal”: In full traffic mode , all data transfers are allowed and happe...
Keep reading

Omar to kill me

By -
Image
  The sentence “ Omar m’a tuer ” is unintelligible French, as if it had been written by an illiterate person. At first sight, Mme Ghislaine Marchal —the author of those words in blood—seems to be saying that she had been killed by Omar in her villa at Mougins (Alpes-Maritimes). But why would that dying French lady have used such poor grammar? On that flimsy evidence, in 1991, the Moroccan gardener Omar Raddad was condemned and jailed. But he persisted non-stop upon his innocence. In 1998, he was liberated, and now lives in Morocco. A recent analysis of DNA specimens from the scene of the crime provides new facts. Four males, none of whom was Omar Raddad, have left traces of their presence. Will the real murderer be identified at last?
Keep reading