doc/api/console.markdown

   1 # Console
   2
   3     Stability: 2 - Stable
   4
   5 The module defines a `Console` class and exports a `console` object.
   6
   7 The `console` object is a special instance of `Console` whose output is
   8 sent to stdout or stderr.
   9
  10 For ease of use, `console` is defined as a global object and can be used
  11 directly without `require`.
  12
  13 ## console
  14
  15 * {Object}
  16
  17 <!--type=global-->
  18
  19 For printing to stdout and stderr. Similar to the console object functions
  20 provided by most web browsers, here the output is sent to stdout or stderr.
  21
  22 The console functions are synchronous when the destination is a terminal or
  23 a file (to avoid lost messages in case of premature exit) and asynchronous
  24 when it's a pipe (to avoid blocking for long periods of time).
  25
  26 That is, in the following example, stdout is non-blocking while stderr
  27 is blocking:
  28
  29     $ node script.js 2> error.log | tee info.log
  30
  31 In daily use, the blocking/non-blocking dichotomy is not something you
  32 should worry about unless you log huge amounts of data.
  33
  34
  35 ### console.log([data][, ...])
  36
  37 Prints to stdout with newline. This function can take multiple arguments in a
  38 `printf()`-like way. Example:
  39
  40     var count = 5;
  41     console.log('count: %d', count);
  42     // prints 'count: 5'
  43
  44 If formatting elements are not found in the first string then `util.inspect`
  45 is used on each argument.  See [util.format()][] for more information.
  46
  47 ### console.info([data][, ...])
  48
  49 Same as `console.log`.
  50
  51 ### console.error([data][, ...])
  52
  53 Same as `console.log` but prints to stderr.
  54
  55 ### console.warn([data][, ...])
  56
  57 Same as `console.error`.
  58
  59 ### console.dir(obj[, options])
  60
  61 Uses `util.inspect` on `obj` and prints resulting string to stdout. This function
  62 bypasses any custom `inspect()` function on `obj`. An optional *options* object
  63 may be passed that alters certain aspects of the formatted string:
  64
  65 - `showHidden` - if `true` then the object's non-enumerable and symbol
  66 properties will be shown too. Defaults to `false`.
  67
  68 - `depth` - tells `inspect` how many times to recurse while formatting the
  69 object. This is useful for inspecting large complicated objects. Defaults to
  70 `2`. To make it recurse indefinitely pass `null`.
  71
  72 - `colors` - if `true`, then the output will be styled with ANSI color codes.
  73 Defaults to `false`. Colors are customizable, see below.
  74
  75 ### console.time(label)
  76
  77 Used to calculate the duration of a specific operation. To start a timer, call
  78 the `console.time()` method, giving it a name as only parameter. To stop the
  79 timer, and to get the elapsed time in milliseconds, just call the
  80 [`console.timeEnd()`](#console_console_timeend_label) method, again passing the
  81 timer's name as the parameter.
  82
  83 ### console.timeEnd(label)
  84
  85 Stops a timer that was previously started by calling
  86 [`console.time()`](#console_console_time_label) and print the result to the
  87 console.
  88
  89 Example:
  90
  91     console.time('100-elements');
  92     for (var i = 0; i < 100; i++) {
  93       ;
  94     }
  95     console.timeEnd('100-elements');
  96     // prints 100-elements: 262ms
  97
  98 ### console.trace(message[, ...])
  99
 100 Print to stderr `'Trace :'`, followed by the formatted message and stack trace
 101 to the current position.
 102
 103 ### console.assert(value[, message][, ...])
 104
 105 Similar to [assert.ok()][], but the error message is formatted as
 106 `util.format(message...)`.
 107
 108 ## Class: Console
 109
 110 <!--type=class-->
 111
 112 Use `require('console').Console` or `console.Console` to access this class.
 113
 114     var Console = require('console').Console;
 115     var Console = console.Console;
 116
 117 You can use `Console` class to custom simple logger like `console`, but with
 118 different output streams.
 119
 120 ### new Console(stdout[, stderr])
 121
 122 Create a new `Console` by passing one or two writable stream instances.
 123 `stdout` is a writable stream to print log or info output. `stderr`
 124 is used for warning or error output. If `stderr` isn't passed, the warning
 125 and error output will be sent to the `stdout`.
 126
 127     var output = fs.createWriteStream('./stdout.log');
 128     var errorOutput = fs.createWriteStream('./stderr.log');
 129     // custom simple logger
 130     var logger = new Console(output, errorOutput);
 131     // use it like console
 132     var count = 5;
 133     logger.log('count: %d', count);
 134     // in stdout.log: count 5
 135
 136 The global `console` is a special `Console` whose output is sent to
 137 `process.stdout` and `process.stderr`:
 138
 139     new Console(process.stdout, process.stderr);
 140
 141 [assert.ok()]: assert.html#assert_assert_value_message_assert_ok_value_message
 142 [util.format()]: util.html#util_util_format_format