200 lines
6.6 KiB
Markdown
200 lines
6.6 KiB
Markdown
|
# debug
|
||
|
|
|
||
|
|
tiny node.js debugging utility modelled after node core's debugging technique.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
```bash
|
||
|
|
$ npm install debug
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
With `debug` you simply invoke the exported function to generate your debug function, passing it a name which will determine if a noop function is returned, or a decorated `console.error`, so all of the `console` [format string goodies](https://developer.chrome.com/devtools/docs/console-api#consolelogobject-object) you're used to work fine. A unique color is selected per-function for visibility.
|
||
|
|
|
||
|
|
Example _app.js_:
|
||
|
|
|
||
|
|
```js
|
||
|
|
var debug = require('debug')('http')
|
||
|
|
, http = require('http')
|
||
|
|
, name = 'My App';
|
||
|
|
|
||
|
|
// fake app
|
||
|
|
|
||
|
|
debug('booting %s', name);
|
||
|
|
|
||
|
|
http.createServer(function(req, res){
|
||
|
|
debug(req.method + ' ' + req.url);
|
||
|
|
res.end('hello\n');
|
||
|
|
}).listen(3000, function(){
|
||
|
|
debug('listening');
|
||
|
|
});
|
||
|
|
|
||
|
|
// fake worker of some kind
|
||
|
|
|
||
|
|
require('./worker');
|
||
|
|
```
|
||
|
|
|
||
|
|
Example _worker.js_:
|
||
|
|
|
||
|
|
```js
|
||
|
|
var debug = require('debug')('worker');
|
||
|
|
|
||
|
|
setInterval(function(){
|
||
|
|
debug('doing some work');
|
||
|
|
}, 1000);
|
||
|
|
```
|
||
|
|
|
||
|
|
The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
#### Windows note
|
||
|
|
|
||
|
|
On Windows the environment variable is set using the `set` command.
|
||
|
|
|
||
|
|
```cmd
|
||
|
|
set DEBUG=*,-not_this
|
||
|
|
```
|
||
|
|
|
||
|
|
Note that PowerShell using different syntax to set environment variables.
|
||
|
|
|
||
|
|
```cmd
|
||
|
|
$env:DEBUG = "*,-not_this"
|
||
|
|
```
|
||
|
|
|
||
|
|
Then, run the program to be debugged as usual.
|
||
|
|
|
||
|
|
## Millisecond diff
|
||
|
|
|
||
|
|
When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## Conventions
|
||
|
|
|
||
|
|
If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".
|
||
|
|
|
||
|
|
## Wildcards
|
||
|
|
|
||
|
|
The `*` character may be used as a wildcard. Suppose for example your library has debuggers named "connect:bodyParser", "connect:compress", "connect:session", instead of listing all three with `DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do `DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.
|
||
|
|
|
||
|
|
You can also exclude specific debuggers by prefixing them with a "-" character. For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:".
|
||
|
|
|
||
|
|
## Browser support
|
||
|
|
|
||
|
|
Debug works in the browser as well, currently persisted by `localStorage`. Consider the situation shown below where you have `worker:a` and `worker:b`, and wish to debug both. You can enable this using `localStorage.debug`:
|
||
|
|
|
||
|
|
```js
|
||
|
|
localStorage.debug = 'worker:*'
|
||
|
|
```
|
||
|
|
|
||
|
|
And then refresh the page.
|
||
|
|
|
||
|
|
```js
|
||
|
|
a = debug('worker:a');
|
||
|
|
b = debug('worker:b');
|
||
|
|
|
||
|
|
setInterval(function(){
|
||
|
|
a('doing some work');
|
||
|
|
}, 1000);
|
||
|
|
|
||
|
|
setInterval(function(){
|
||
|
|
b('doing some work');
|
||
|
|
}, 1200);
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Web Inspector Colors
|
||
|
|
|
||
|
|
Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
|
||
|
|
option. These are WebKit web inspectors, Firefox ([since version
|
||
|
|
31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
|
||
|
|
and the Firebug plugin for Firefox (any version).
|
||
|
|
|
||
|
|
Colored output looks something like:
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## Output streams
|
||
|
|
|
||
|
|
|
||
|
|
### stderr vs stdout
|
||
|
|
By default `debug` will log to stderr, however this can be changed by setting the environment variable `DEBUG_FD` to `1` for stdout and `2` for stderr (the default value).
|
||
|
|
|
||
|
|
You can also set an alternative logging method per-namespace by overriding the `log` method on a per-namespace or globally:
|
||
|
|
|
||
|
|
Example _stdout.js_:
|
||
|
|
|
||
|
|
```js
|
||
|
|
var debug = require('debug');
|
||
|
|
var error = debug('app:error');
|
||
|
|
|
||
|
|
// by default stderr is used
|
||
|
|
error('goes to stderr!');
|
||
|
|
|
||
|
|
var log = debug('app:log');
|
||
|
|
// set this namespace to log via console.log
|
||
|
|
log.log = console.log.bind(console); // don't forget to bind to console!
|
||
|
|
log('goes to stdout');
|
||
|
|
error('still goes to stderr!');
|
||
|
|
|
||
|
|
// set all output to go via console.info
|
||
|
|
// overrides all per-namespace log settings
|
||
|
|
debug.log = console.info.bind(console);
|
||
|
|
error('now goes to stdout via console.info');
|
||
|
|
log('still goes to stdout, but via console.info now');
|
||
|
|
```
|
||
|
|
|
||
|
|
### Save debug output to a file
|
||
|
|
|
||
|
|
You can save all debug statements to a file by piping them.
|
||
|
|
|
||
|
|
Example:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
$ DEBUG_FD=3 node your-app.js 3> whatever.log
|
||
|
|
```
|
||
|
|
|
||
|
|
### Terminal colors
|
||
|
|
|
||
|
|
By default colors will only be used in a TTY. However this can be overridden by setting the environment variable `DEBUG_COLORS` to `1`.
|
||
|
|
|
||
|
|
Note: Certain IDEs (such as WebStorm) don't support colors on stderr. In these cases you must set `DEBUG_COLORS` to `1` and additionally change `DEBUG_FD` to `1`.
|
||
|
|
|
||
|
|
## Authors
|
||
|
|
|
||
|
|
- TJ Holowaychuk
|
||
|
|
- Nathan Rajlich
|
||
|
|
- Andrew Rhyne
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
(The MIT License)
|
||
|
|
|
||
|
|
Copyright (c) 2014-2016 TJ Holowaychuk <tj@vision-media.ca>
|
||
|
|
|
||
|
|
Permission is hereby granted, free of charge, to any person obtaining
|
||
|
|
a copy of this software and associated documentation files (the
|
||
|
|
'Software'), to deal in the Software without restriction, including
|
||
|
|
without limitation the rights to use, copy, modify, merge, publish,
|
||
|
|
distribute, sublicense, and/or sell copies of the Software, and to
|
||
|
|
permit persons to whom the Software is furnished to do so, subject to
|
||
|
|
the following conditions:
|
||
|
|
|
||
|
|
The above copyright notice and this permission notice shall be
|
||
|
|
included in all copies or substantial portions of the Software.
|
||
|
|
|
||
|
|
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
||
|
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||
|
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||
|
|
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||
|
|
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||
|
|
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||
|
|
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|