1 | # debug
|
---|
2 | [![Build Status](https://travis-ci.org/visionmedia/debug.svg?branch=master)](https://travis-ci.org/visionmedia/debug) [![Coverage Status](https://coveralls.io/repos/github/visionmedia/debug/badge.svg?branch=master)](https://coveralls.io/github/visionmedia/debug?branch=master) [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers)
|
---|
3 | [![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#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 | ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)
|
---|
57 |
|
---|
58 | ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)
|
---|
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 | ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)
|
---|
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 | ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)
|
---|
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 | ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)
|
---|
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.
|
---|