doc/api/console.markdown

# Console

    Stability: 2 - Stable

The `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* A `Console` class with methods such as `console.log()`, `console.error()` and
  `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to `stdout` and `stderr`.
  Because this object is global, it can be used without calling
  `require('console')`.

Example using the global `console`:

    console.log('hello world');
      // Prints: hello world, to stdout
    console.log('hello %s', 'world');
      // Prints: hello world, to stdout
    console.error(new Error('Whoops, something bad happened'));
      // Prints: [Error: Whoops, something bad happened], to stderr

    const name = 'Will Robinson';
    console.warn(`Danger ${name}! Danger!`);
      // Prints: Danger Will Robinson! Danger!, to stderr

Example using the `Console` class:

    const out = getStreamSomehow();
    const err = getStreamSomehow();
    const myConsole = new console.Console(out, err);

    myConsole.log('hello world');
      // Prints: hello world, to out
    myConsole.log('hello %s', 'world');
      // Prints: hello world, to out
    myConsole.error(new Error('Whoops, something bad happened'));
      // Prints: [Error: Whoops, something bad happened], to err

    const name = 'Will Robinson';
    myConsole.warn(`Danger ${name}! Danger!`);
      // Prints: Danger Will Robinson! Danger!, to err

While the API for the `Console` class is designed fundamentally around the
Web browser `console` object, the `Console` is Node.js is *not* intended to
duplicate the browsers functionality exactly.

## Asynchronous vs Synchronous Consoles

The console functions are synchronous when the destination is a terminal or
a file (to avoid lost messages in case of premature exit) and asynchronous
when the destination is a pipe (to avoid blocking for long periods of time).

In the following example, stdout is non-blocking while stderr is blocking:

    $ node script.js 2> error.log | tee info.log

Typically, the distinction between blocking/non-blocking is not important
unless an application is logging significant amounts of data. High volume
logging *should* use a `Console` instance that writes to a pipe.

## Class: Console

<!--type=class-->

The `Console` class can be used to create a simple logger with configurable
output streams and can be accessed using either `require('console').Console`
or `console.Console`:

    const Console = require('console').Console;
    const Console = console.Console;

### new Console(stdout[, stderr])

Creates a new `Console` by passing one or two writable stream instances.
`stdout` is a writable stream to print log or info output. `stderr`
is used for warning or error output. If `stderr` isn't passed, the warning
and error output will be sent to the `stdout`.

    const output = fs.createWriteStream('./stdout.log');
    const errorOutput = fs.createWriteStream('./stderr.log');
    // custom simple logger
    const logger = new Console(output, errorOutput);
    // use it like console
    var count = 5;
    logger.log('count: %d', count);
    // in stdout.log: count 5

The global `console` is a special `Console` whose output is sent to
`process.stdout` and `process.stderr`. It is equivalent to calling:

    new Console(process.stdout, process.stderr);

### console.assert(value[, message][, ...])

A simple assertion test that verifies whether `value` is truthy. If it is not,
an `AssertionError` is throw. If provided, the error `message` is formatted
using [`util.format()`][] and used as the error message.

    console.assert(true, 'does nothing');
      // OK
    console.assert(false, 'Whoops %s', 'didn\'t work');
      // AssertionError: Whoops didn't work

### console.dir(obj[, options])

Uses [`util.inspect()`][] on `obj` and prints the resulting string to stdout.
This function bypasses any custom `inspect()` function defined on `obj`. An
optional `options` object may be passed that alters certain aspects of the
formatted string:

- `showHidden` - if `true` then the object's non-enumerable and symbol
properties will be shown too. Defaults to `false`.

- `depth` - tells `inspect` how many times to recurse while formatting the
object. This is useful for inspecting large complicated objects. Defaults to
`2`. To make it recurse indefinitely, pass `null`.

- `colors` - if `true`, then the output will be styled with ANSI color codes.
Defaults to `false`. Colors are customizable; see
[customizing `util.inspect()` colors][].

### console.error([data][, ...])

Prints to stderr with newline. Multiple arguments can be passed, with the first
used as the primary message and all additional used as substitution
values similar to `printf()` (the arguments are all passed to
[`util.format()`][]).

    const code = 5;
    console.error('error #%d', code);
      // Prints: error #5, to stderr
    console.error('error', code);
      // Prints: error 5, to stderr

If formatting elements (e.g. `%d`) are not found in the first string then
[`util.inspect()`][] is called on each argument and the resulting string
values are concatenated.  See [`util.format()`][] for more information.

### console.info([data][, ...])

The `console.info()` function is an alias for [`console.log()`][].

### console.log([data][, ...])

Prints to stdout with newline. Multiple arguments can be passed, with the first
used as the primary message and all additional used as substitution
values similar to `printf()` (the arguments are all passed to
[`util.format()`][]).

    var count = 5;
    console.log('count: %d', count);
      // Prints: count: 5, to stdout
    console.log('count: ', count);
      // Prints: count: 5, to stdout

If formatting elements (e.g. `%d`) are not found in the first string then
[`util.inspect()`][] is called on each argument and the resulting string
values are concatenated.  See [`util.format()`][] for more information.

### console.time(label)

Used to calculate the duration of a specific operation. To start a timer, call
the `console.time()` method, giving it a unique `label` as the only parameter. To stop the
timer, and to get the elapsed time in milliseconds, just call the
[`console.timeEnd()`][] method, again passing the
timer's unique `label` as the parameter.

### console.timeEnd(label)

Stops a timer that was previously started by calling [`console.time()`][] and
prints the result to stdout:

    console.time('100-elements');
    for (var i = 0; i < 100; i++) {
      ;
    }
    console.timeEnd('100-elements');
    // prints 100-elements: 262ms

### console.trace(message[, ...])

Prints to stderr the string `'Trace :'`, followed by the [`util.format()`][]
formatted message and stack trace to the current position in the code.

    console.trace('Show me');
      // Prints: (stack trace will vary based on where trace is called)
      //  Trace: Show me
      //    at repl:2:9
      //    at REPLServer.defaultEval (repl.js:248:27)
      //    at bound (domain.js:287:14)
      //    at REPLServer.runBound [as eval] (domain.js:300:12)
      //    at REPLServer.<anonymous> (repl.js:412:12)
      //    at emitOne (events.js:82:20)
      //    at REPLServer.emit (events.js:169:7)
      //    at REPLServer.Interface._onLine (readline.js:210:10)
      //    at REPLServer.Interface._line (readline.js:549:8)
      //    at REPLServer.Interface._ttyWrite (readline.js:826:14)

### console.warn([data][, ...])

The `console.warn()` function is an alias for [`console.error()`][].

[`console.error()`]: #console_console_error_data
[`console.log()`]: #console_console_log_data
[`console.time()`]: #console_console_time_label
[`console.timeEnd()`]: #console_console_timeend_label
[`util.format()`]: util.html#util_util_format_format
[`util.inspect()`]: util.html#util_util_inspect_object_options