1 | # debug
|
2 |
|
3 | tiny node.js debugging utility modelled after node core's debugging technique.
|
4 |
|
5 | ## Installation
|
6 |
|
7 | ```bash
|
8 | $ npm install debug
|
9 | ```
|
10 |
|
11 | ## Usage
|
12 |
|
13 | 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 you're used to work fine. A unique color is selected per-function for visibility.
|
14 |
|
15 | Example _app.js_:
|
16 |
|
17 | ```js
|
18 | var debug = require('debug')('http')
|
19 | , http = require('http')
|
20 | , name = 'My App';
|
21 |
|
22 | // fake app
|
23 |
|
24 | debug('booting %s', name);
|
25 |
|
26 | http.createServer(function(req, res){
|
27 | debug(req.method + ' ' + req.url);
|
28 | res.end('hello\n');
|
29 | }).listen(3000, function(){
|
30 | debug('listening');
|
31 | });
|
32 |
|
33 | // fake worker of some kind
|
34 |
|
35 | require('./worker');
|
36 | ```
|
37 |
|
38 | Example _worker.js_:
|
39 |
|
40 | ```js
|
41 | var debug = require('debug')('worker');
|
42 |
|
43 | setInterval(function(){
|
44 | debug('doing some work');
|
45 | }, 1000);
|
46 | ```
|
47 |
|
48 | The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:
|
49 |
|
50 | ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)
|
51 |
|
52 | ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)
|
53 |
|
54 | ## Millisecond diff
|
55 |
|
56 | 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.
|
57 |
|
58 | ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)
|
59 |
|
60 | When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:
|
61 |
|
62 | ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)
|
63 |
|
64 | ## Conventions
|
65 |
|
66 | 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".
|
67 |
|
68 | ## Wildcards
|
69 |
|
70 | 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=*`.
|
71 |
|
72 | 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:".
|
73 |
|
74 | ## Browser support
|
75 |
|
76 | Debug works in the browser as well, currently persisted by `localStorage`. For example if you have `worker:a` and `worker:b` as shown below, and wish to debug both type `debug.enable('worker:*')` in the console and refresh the page, this will remain until you disable with `debug.disable()`.
|
77 |
|
78 | ```js
|
79 | a = debug('worker:a');
|
80 | b = debug('worker:b');
|
81 |
|
82 | setInterval(function(){
|
83 | a('doing some work');
|
84 | }, 1000);
|
85 |
|
86 | setInterval(function(){
|
87 | b('doing some work');
|
88 | }, 1200);
|
89 | ```
|
90 |
|
91 | #### Web Inspector Colors
|
92 |
|
93 | Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
|
94 | option. These are WebKit web inspectors, Firefox ([since version
|
95 | 31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
|
96 | and the Firebug plugin for Firefox (any version).
|
97 |
|
98 | Colored output looks something like:
|
99 |
|
100 | ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)
|
101 |
|
102 | ### stderr vs stdout
|
103 |
|
104 | You can set an alternative logging method per-namespace by overriding the `log` method on a per-namespace or globally:
|
105 |
|
106 | Example _stderr.js_:
|
107 |
|
108 | ```js
|
109 | var debug = require('../');
|
110 | var log = debug('app:log');
|
111 |
|
112 | // by default console.log is used
|
113 | log('goes to stdout!');
|
114 |
|
115 | var error = debug('app:error');
|
116 | // set this namespace to log via console.error
|
117 | error.log = console.error.bind(console); // don't forget to bind to console!
|
118 | error('goes to stderr');
|
119 | log('still goes to stdout!');
|
120 |
|
121 | // set all output to go via console.warn
|
122 | // overrides all per-namespace log settings
|
123 | debug.log = console.warn.bind(console);
|
124 | log('now goes to stderr via console.warn');
|
125 | error('still goes to stderr, but via console.warn now');
|
126 | ```
|
127 |
|
128 | ## Authors
|
129 |
|
130 | - TJ Holowaychuk
|
131 | - Nathan Rajlich
|
132 |
|
133 | ## License
|
134 |
|
135 | (The MIT License)
|
136 |
|
137 | Copyright (c) 2014 TJ Holowaychuk <tj@vision-media.ca>
|
138 |
|
139 | Permission is hereby granted, free of charge, to any person obtaining
|
140 | a copy of this software and associated documentation files (the
|
141 | 'Software'), to deal in the Software without restriction, including
|
142 | without limitation the rights to use, copy, modify, merge, publish,
|
143 | distribute, sublicense, and/or sell copies of the Software, and to
|
144 | permit persons to whom the Software is furnished to do so, subject to
|
145 | the following conditions:
|
146 |
|
147 | The above copyright notice and this permission notice shall be
|
148 | included in all copies or substantial portions of the Software.
|
149 |
|
150 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
151 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
152 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
153 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
154 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
155 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
156 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|