|
1
|
# debug
|
|
2
|
[](https://travis-ci.org/visionmedia/debug) [](https://coveralls.io/github/visionmedia/debug?branch=master) [](https://visionmedia-community-slackin.now.sh/) [](#backers)
|
|
3
|
[](#sponsors)
|
|
4
|
|
|
5
|
|
|
6
|
|
|
7
|
A tiny node.js debugging utility modelled after node core's debugging technique.
|
|
8
|
|
|
9
|
**Discussion around the V3 API is under way [here](https://github.com/visionmedia/debug/issues/370)**
|
|
10
|
|
|
11
|
## Installation
|
|
12
|
|
|
13
|
```bash
|
|
14
|
$ npm install debug
|
|
15
|
```
|
|
16
|
|
|
17
|
## Usage
|
|
18
|
|
|
19
|
`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.
|
|
20
|
|
|
21
|
Example _app.js_:
|
|
22
|
|
|
23
|
```js
|
|
24
|
var debug = require('debug')('http')
|
|
25
|
, http = require('http')
|
|
26
|
, name = 'My App';
|
|
27
|
|
|
28
|
// fake app
|
|
29
|
|
|
30
|
debug('booting %s', name);
|
|
31
|
|
|
32
|
http.createServer(function(req, res){
|
|
33
|
debug(req.method + ' ' + req.url);
|
|
34
|
res.end('hello\n');
|
|
35
|
}).listen(3000, function(){
|
|
36
|
debug('listening');
|
|
37
|
});
|
|
38
|
|
|
39
|
// fake worker of some kind
|
|
40
|
|
|
41
|
require('./worker');
|
|
42
|
```
|
|
43
|
|
|
44
|
Example _worker.js_:
|
|
45
|
|
|
46
|
```js
|
|
47
|
var debug = require('debug')('worker');
|
|
48
|
|
|
49
|
setInterval(function(){
|
|
50
|
debug('doing some work');
|
|
51
|
}, 1000);
|
|
52
|
```
|
|
53
|
|
|
54
|
The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:
|
|
55
|
|
|
56
|
|
|
57
|
|
|
58
|
|
|
59
|
|
|
60
|
#### Windows note
|
|
61
|
|
|
62
|
On Windows the environment variable is set using the `set` command.
|
|
63
|
|
|
64
|
```cmd
|
|
65
|
set DEBUG=*,-not_this
|
|
66
|
```
|
|
67
|
|
|
68
|
Note that PowerShell uses different syntax to set environment variables.
|
|
69
|
|
|
70
|
```cmd
|
|
71
|
$env:DEBUG = "*,-not_this"
|
|
72
|
```
|
|
73
|
|
|
74
|
Then, run the program to be debugged as usual.
|
|
75
|
|
|
76
|
## Millisecond diff
|
|
77
|
|
|
78
|
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.
|
|
79
|
|
|
80
|
|
|
81
|
|
|
82
|
When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:
|
|
83
|
|
|
84
|
|
|
85
|
|
|
86
|
## Conventions
|
|
87
|
|
|
88
|
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".
|
|
89
|
|
|
90
|
## Wildcards
|
|
91
|
|
|
92
|
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=*`.
|
|
93
|
|
|
94
|
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:".
|
|
95
|
|
|
96
|
## Environment Variables
|
|
97
|
|
|
98
|
When running through Node.js, you can set a few environment variables that will
|
|
99
|
change the behavior of the debug logging:
|
|
100
|
|
|
101
|
| Name | Purpose |
|
|
102
|
|-----------|-------------------------------------------------|
|
|
103
|
| `DEBUG` | Enables/disables specific debugging namespaces. |
|
|
104
|
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
|
|
105
|
| `DEBUG_DEPTH` | Object inspection depth. |
|
|
106
|
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |
|
|
107
|
|
|
108
|
|
|
109
|
__Note:__ The environment variables beginning with `DEBUG_` end up being
|
|
110
|
converted into an Options object that gets used with `%o`/`%O` formatters.
|
|
111
|
See the Node.js documentation for
|
|
112
|
[`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
|
|
113
|
for the complete list.
|
|
114
|
|
|
115
|
## Formatters
|
|
116
|
|
|
117
|
|
|
118
|
Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. Below are the officially supported formatters:
|
|
119
|
|
|
120
|
| Formatter | Representation |
|
|
121
|
|-----------|----------------|
|
|
122
|
| `%O` | Pretty-print an Object on multiple lines. |
|
|
123
|
| `%o` | Pretty-print an Object all on a single line. |
|
|
124
|
| `%s` | String. |
|
|
125
|
| `%d` | Number (both integer and float). |
|
|
126
|
| `%j` | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
|
|
127
|
| `%%` | Single percent sign ('%'). This does not consume an argument. |
|
|
128
|
|
|
129
|
### Custom formatters
|
|
130
|
|
|
131
|
You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like:
|
|
132
|
|
|
133
|
```js
|
|
134
|
const createDebug = require('debug')
|
|
135
|
createDebug.formatters.h = (v) => {
|
|
136
|
return v.toString('hex')
|
|
137
|
}
|
|
138
|
|
|
139
|
// …elsewhere
|
|
140
|
const debug = createDebug('foo')
|
|
141
|
debug('this is hex: %h', new Buffer('hello world'))
|
|
142
|
// foo this is hex: 68656c6c6f20776f726c6421 +0ms
|
|
143
|
```
|
|
144
|
|
|
145
|
## Browser support
|
|
146
|
You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
|
|
147
|
or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
|
|
148
|
if you don't want to build it yourself.
|
|
149
|
|
|
150
|
Debug's enable state is currently persisted by `localStorage`.
|
|
151
|
Consider the situation shown below where you have `worker:a` and `worker:b`,
|
|
152
|
and wish to debug both. You can enable this using `localStorage.debug`:
|
|
153
|
|
|
154
|
```js
|
|
155
|
localStorage.debug = 'worker:*'
|
|
156
|
```
|
|
157
|
|
|
158
|
And then refresh the page.
|
|
159
|
|
|
160
|
```js
|
|
161
|
a = debug('worker:a');
|
|
162
|
b = debug('worker:b');
|
|
163
|
|
|
164
|
setInterval(function(){
|
|
165
|
a('doing some work');
|
|
166
|
}, 1000);
|
|
167
|
|
|
168
|
setInterval(function(){
|
|
169
|
b('doing some work');
|
|
170
|
}, 1200);
|
|
171
|
```
|
|
172
|
|
|
173
|
#### Web Inspector Colors
|
|
174
|
|
|
175
|
Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
|
|
176
|
option. These are WebKit web inspectors, Firefox ([since version
|
|
177
|
31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
|
|
178
|
and the Firebug plugin for Firefox (any version).
|
|
179
|
|
|
180
|
Colored output looks something like:
|
|
181
|
|
|
182
|
|
|
183
|
|
|
184
|
|
|
185
|
## Output streams
|
|
186
|
|
|
187
|
By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:
|
|
188
|
|
|
189
|
Example _stdout.js_:
|
|
190
|
|
|
191
|
```js
|
|
192
|
var debug = require('debug');
|
|
193
|
var error = debug('app:error');
|
|
194
|
|
|
195
|
// by default stderr is used
|
|
196
|
error('goes to stderr!');
|
|
197
|
|
|
198
|
var log = debug('app:log');
|
|
199
|
// set this namespace to log via console.log
|
|
200
|
log.log = console.log.bind(console); // don't forget to bind to console!
|
|
201
|
log('goes to stdout');
|
|
202
|
error('still goes to stderr!');
|
|
203
|
|
|
204
|
// set all output to go via console.info
|
|
205
|
// overrides all per-namespace log settings
|
|
206
|
debug.log = console.info.bind(console);
|
|
207
|
error('now goes to stdout via console.info');
|
|
208
|
log('still goes to stdout, but via console.info now');
|
|
209
|
```
|
|
210
|
|
|
211
|
|
|
212
|
## Authors
|
|
213
|
|
|
214
|
- TJ Holowaychuk
|
|
215
|
- Nathan Rajlich
|
|
216
|
- Andrew Rhyne
|
|
217
|
|
|
218
|
## Backers
|
|
219
|
|
|
220
|
Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]
|
|
221
|
|
|
222
|
<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
|
|
223
|
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
|
|
224
|
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
|
|
225
|
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
|
|
226
|
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
|
|
227
|
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
|
|
228
|
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
|
|
229
|
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
|
|
230
|
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
|
|
231
|
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
|
|
232
|
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
|
|
233
|
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
|
|
234
|
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
|
|
235
|
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
|
|
236
|
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
|
|
237
|
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
|
|
238
|
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
|
|
239
|
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
|
|
240
|
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
|
|
241
|
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
|
|
242
|
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
|
|
243
|
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
|
|
244
|
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
|
|
245
|
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
|
|
246
|
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
|
|
247
|
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
|
|
248
|
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
|
|
249
|
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
|
|
250
|
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
|
|
251
|
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>
|
|
252
|
|
|
253
|
|
|
254
|
## Sponsors
|
|
255
|
|
|
256
|
Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]
|
|
257
|
|
|
258
|
<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
|
|
259
|
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
|
|
260
|
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
|
|
261
|
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
|
|
262
|
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
|
|
263
|
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
|
|
264
|
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
|
|
265
|
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
|
|
266
|
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
|
|
267
|
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
|
|
268
|
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
|
|
269
|
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
|
|
270
|
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
|
|
271
|
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
|
|
272
|
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
|
|
273
|
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
|
|
274
|
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
|
|
275
|
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
|
|
276
|
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
|
|
277
|
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
|
|
278
|
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
|
|
279
|
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
|
|
280
|
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
|
|
281
|
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
|
|
282
|
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
|
|
283
|
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
|
|
284
|
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
|
|
285
|
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
|
|
286
|
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
|
|
287
|
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>
|
|
288
|
|
|
289
|
## License
|
|
290
|
|
|
291
|
(The MIT License)
|
|
292
|
|
|
293
|
Copyright (c) 2014-2016 TJ Holowaychuk <tj@vision-media.ca>
|
|
294
|
|
|
295
|
Permission is hereby granted, free of charge, to any person obtaining
|
|
296
|
a copy of this software and associated documentation files (the
|
|
297
|
'Software'), to deal in the Software without restriction, including
|
|
298
|
without limitation the rights to use, copy, modify, merge, publish,
|
|
299
|
distribute, sublicense, and/or sell copies of the Software, and to
|
|
300
|
permit persons to whom the Software is furnished to do so, subject to
|
|
301
|
the following conditions:
|
|
302
|
|
|
303
|
The above copyright notice and this permission notice shall be
|
|
304
|
included in all copies or substantial portions of the Software.
|
|
305
|
|
|
306
|
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
|
307
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
308
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
309
|
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
|
310
|
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
|
311
|
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
|
312
|
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|