corrade-nucleus-nucleons – Blame information for rev 36
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
36 | office | 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 | #### Windows note |
||
55 | |||
56 | On Windows the environment variable is set using the `set` command. |
||
57 | |||
58 | ```cmd |
||
59 | set DEBUG=*,-not_this |
||
60 | ``` |
||
61 | |||
62 | Then, run the program to be debugged as usual. |
||
63 | |||
64 | ## Millisecond diff |
||
65 | |||
66 | 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. |
||
67 | |||
68 | ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png) |
||
69 | |||
70 | When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below: |
||
71 | |||
72 | ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png) |
||
73 | |||
74 | ## Conventions |
||
75 | |||
76 | 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". |
||
77 | |||
78 | ## Wildcards |
||
79 | |||
80 | 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=*`. |
||
81 | |||
82 | 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:". |
||
83 | |||
84 | ## Browser support |
||
85 | |||
86 | 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. Somewhere in the code on your page, include: |
||
87 | |||
88 | ```js |
||
89 | window.myDebug = require("debug"); |
||
90 | ``` |
||
91 | |||
92 | ("debug" is a global object in the browser so we give this object a different name.) When your page is open in the browser, type the following in the console: |
||
93 | |||
94 | ```js |
||
95 | myDebug.enable("worker:*") |
||
96 | ``` |
||
97 | |||
98 | Refresh the page. Debug output will continue to be sent to the console until it is disabled by typing `myDebug.disable()` in the console. |
||
99 | |||
100 | ```js |
||
101 | a = debug('worker:a'); |
||
102 | b = debug('worker:b'); |
||
103 | |||
104 | setInterval(function(){ |
||
105 | a('doing some work'); |
||
106 | }, 1000); |
||
107 | |||
108 | setInterval(function(){ |
||
109 | b('doing some work'); |
||
110 | }, 1200); |
||
111 | ``` |
||
112 | |||
113 | #### Web Inspector Colors |
||
114 | |||
115 | Colors are also enabled on "Web Inspectors" that understand the `%c` formatting |
||
116 | option. These are WebKit web inspectors, Firefox ([since version |
||
117 | 31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/)) |
||
118 | and the Firebug plugin for Firefox (any version). |
||
119 | |||
120 | Colored output looks something like: |
||
121 | |||
122 | ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png) |
||
123 | |||
124 | ### stderr vs stdout |
||
125 | |||
126 | You can set an alternative logging method per-namespace by overriding the `log` method on a per-namespace or globally: |
||
127 | |||
128 | Example _stdout.js_: |
||
129 | |||
130 | ```js |
||
131 | var debug = require('debug'); |
||
132 | var error = debug('app:error'); |
||
133 | |||
134 | // by default stderr is used |
||
135 | error('goes to stderr!'); |
||
136 | |||
137 | var log = debug('app:log'); |
||
138 | // set this namespace to log via console.log |
||
139 | log.log = console.log.bind(console); // don't forget to bind to console! |
||
140 | log('goes to stdout'); |
||
141 | error('still goes to stderr!'); |
||
142 | |||
143 | // set all output to go via console.info |
||
144 | // overrides all per-namespace log settings |
||
145 | debug.log = console.info.bind(console); |
||
146 | error('now goes to stdout via console.info'); |
||
147 | log('still goes to stdout, but via console.info now'); |
||
148 | ``` |
||
149 | |||
150 | ### Save debug output to a file |
||
151 | |||
152 | You can save all debug statements to a file by piping them. |
||
153 | |||
154 | Example: |
||
155 | |||
156 | ```bash |
||
157 | $ DEBUG_FD=3 node your-app.js 3> whatever.log |
||
158 | ``` |
||
159 | |||
160 | ## Authors |
||
161 | |||
162 | - TJ Holowaychuk |
||
163 | - Nathan Rajlich |
||
164 | |||
165 | ## License |
||
166 | |||
167 | (The MIT License) |
||
168 | |||
169 | Copyright (c) 2014 TJ Holowaychuk <tj@vision-media.ca> |
||
170 | |||
171 | Permission is hereby granted, free of charge, to any person obtaining |
||
172 | a copy of this software and associated documentation files (the |
||
173 | 'Software'), to deal in the Software without restriction, including |
||
174 | without limitation the rights to use, copy, modify, merge, publish, |
||
175 | distribute, sublicense, and/or sell copies of the Software, and to |
||
176 | permit persons to whom the Software is furnished to do so, subject to |
||
177 | the following conditions: |
||
178 | |||
179 | The above copyright notice and this permission notice shall be |
||
180 | included in all copies or substantial portions of the Software. |
||
181 | |||
182 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, |
||
183 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
||
184 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
||
185 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY |
||
186 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, |
||
187 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE |
||
188 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |