Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 1063 lines (820 sloc) 36.828 kB
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
1 Bunyan is **a simple and fast JSON logging library** for node.js services:
2
3 var bunyan = require('bunyan');
4 var log = bunyan.createLogger({name: "myapp"});
5 log.info("hi");
6
7 and **a `bunyan` CLI tool** for nicely viewing those logs:
48357d1 @trentm screenshot
authored
8
9 ![bunyan CLI screenshot](https://raw.github.com/trentm/node-bunyan/master/tools/screenshot1.png)
aa166b2 @trentm first stab. 'log.info(...)'
authored
10
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
11 Manifesto: Server logs should be structured. JSON's a good format. Let's do
12 that. A log record is one line of `JSON.stringify`'d output. Let's also
13 specify some common names for the requisite and common fields for a log
14 record (see below).
aa166b2 @trentm first stab. 'log.info(...)'
authored
15
16 Also: log4j is way more than you need.
17
18
b3bd83c @trentm some intro docs
authored
19 # Current Status
20
37a1447 @trentm per issue #8 change the way a raw stream is handled
authored
21 Solid core functionality is there. Joyent is using this for a number of
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
22 production services. Bunyan supports node 0.6 and greater. Follow
23 <a href="https://twitter.com/intent/user?screen_name=trentmick" target="_blank">@trentmick</a>
b91f696 @trentm can I use an <a> in readme?
authored
24 for updates to Bunyan.
25
1514b25 @trentm forum link
authored
26 There is an email discussion list
27 [bunyan-logging@googlegroups.com](mailto:bunyan-logging@googlegroups.com),
28 also [as a forum in the
29 browser](https://groups.google.com/forum/?fromgroups#!forum/bunyan-logging).
1602307 @trentm mention the google group
authored
30
b3bd83c @trentm some intro docs
authored
31
8b3bdef @trentm readme tweaks
authored
32 # Installation
33
34 npm install bunyan
35
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
36 **Tip**: The `bunyan` CLI tool is written to be compatible (within reason) with
37 all versions of Bunyan logs. Therefore you might want to `npm install -g bunyan`
38 to get the bunyan CLI on your PATH, then use local bunyan installs for
39 node.js library usage of bunyan in your apps.
8b3bdef @trentm readme tweaks
authored
40
aa166b2 @trentm first stab. 'log.info(...)'
authored
41
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
42 # Features
43
44 - elegant [log method API](#log-method-api)
45 - extensible [streams](#streams) system for controlling where log records
46 go (to a stream, to a file, [log file rotation](#stream-type-rotating-file),
47 etc.)
48 - [`bunyan` CLI](#cli-usage) for pretty-printing and filtering of Bunyan logs
49 - simple include of log call source location (file, line, function) with
50 [`src: true`](#src)
26a8bb0 @trentm Bright black "hides" some bunyan CLI styled text when using Solarized…
authored
51 - lightweight specialization of Logger instances with [`log.child`](#logchild)
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
52 - custom rendering of logged objects with ["serializers"](#serializers)
fe1e25a @trentm Fix anchor (per @wayneseymour, fixes #152)
authored
53 - [Runtime log snooping via Dtrace support](#runtime-log-snooping-via-dtrace)
414f335 @trentm browserify support, bump ver to 1.1.0
authored
54 - Support for [browserify](http://browserify.org/). See [Browserify
55 section](#browserify) below.
b3bd83c @trentm some intro docs
authored
56
aa166b2 @trentm first stab. 'log.info(...)'
authored
57
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
58 # Introduction
c7d5f8b @trentm [issue #12] Add `bunyan.createLogger(OPTIONS)` form, as is more typic…
authored
59
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
60 Like most logging libraries you create a Logger instance and call methods
61 named after the logging levels:
62
63 $ cat hi.js
c7d5f8b @trentm [issue #12] Add `bunyan.createLogger(OPTIONS)` form, as is more typic…
authored
64 var bunyan = require('bunyan');
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
65 var log = bunyan.createLogger({name: 'myapp'});
66 log.info('hi');
67 log.warn({lang: 'fr'}, 'au revoir');
c7d5f8b @trentm [issue #12] Add `bunyan.createLogger(OPTIONS)` form, as is more typic…
authored
68
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
69 All loggers must provide a "name". This is somewhat akin to the log4j logger
70 "name", but Bunyan doesn't do hierarchical logger names.
71
72 **Bunyan log records are JSON.** A few fields are added automatically:
73 "pid", "hostname", "time" and "v".
b3bd83c @trentm some intro docs
authored
74
aa166b2 @trentm first stab. 'log.info(...)'
authored
75 $ node hi.js
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
76 {"name":"myapp","hostname":"banana.local","pid":40161,"level":30,"msg":"hi","time":"2013-01-04T18:46:23.851Z","v":0}
77 {"name":"myapp","hostname":"banana.local","pid":40161,"level":40,"lang":"fr","msg":"au revoir","time":"2013-01-04T18:46:23.853Z","v":0}
78
b3bd83c @trentm some intro docs
authored
79
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
80 ## Log Method API
81
82 The example above shows two different ways to call `log.info(...)`. The
83 full API is:
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
84
543ef15 @trentm 'log.info(err)' support
authored
85 log.info(); // Returns a boolean: is the "info" level enabled?
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
86 // This is equivalent to `log.isInfoEnabled()` or
87 // `log.isEnabledFor(INFO)` in log4j.
0d713a4 @trentm improve intro to the 'log.info(...)' API
authored
88
36f7e51 @trentm issue #131 Allow `log.info(<number>)` and, most importantly, don't cr…
authored
89 log.info('hi'); // Log a simple string message (or number).
140c9fd @trentm s/service/name/ for Logger name field. "service" is unnecessarily tie…
authored
90 log.info('hi %s', bob, anotherVar); // Uses `util.format` for msg formatting.
0d713a4 @trentm improve intro to the 'log.info(...)' API
authored
91
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
92 log.info({foo: 'bar'}, 'hi');
93 // Adds "foo" field to log record. You can add any number
94 // of additional fields here.
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
95
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
96 log.info(err); // Special case to log an `Error` instance to the record.
97 // This adds an "err" field with exception details
98 // (including the stack) and sets "msg" to the exception
99 // message.
0d713a4 @trentm improve intro to the 'log.info(...)' API
authored
100 log.info(err, 'more on this: %s', more);
101 // ... or you can specify the "msg".
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
102
cb6e849 @trentm add warning about `log.info(myobj)` as both Yunong and Orlando have h…
authored
103 Note that this implies **you cannot pass any object as the first argument
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
104 to log it**. IOW, `log.info(mywidget)` may not be what you expect. Instead
105 of a string representation of `mywidget` that other logging libraries may
106 give you, Bunyan will try to JSON-ify your object. It is a Bunyan best
107 practice to always give a field name to included objects, e.g.:
cb6e849 @trentm add warning about `log.info(myobj)` as both Yunong and Orlando have h…
authored
108
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
109 log.info({widget: mywidget}, ...)
cb6e849 @trentm add warning about `log.info(myobj)` as both Yunong and Orlando have h…
authored
110
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
111 This will dove-tail with [Bunyan serializer support](#serializers), discussed
112 later.
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
113
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
114 The same goes for all of Bunyan's log levels: `log.trace`, `log.debug`,
faf2cec @kcivey add `error` to list of log levels in readme
kcivey authored
115 `log.info`, `log.warn`, `log.error`, and `log.fatal`. See the [levels section](#levels)
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
116 below for details and suggestions.
aa166b2 @trentm first stab. 'log.info(...)'
authored
117
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
118
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
119 ## CLI Usage
120
121 Bunyan log output is a stream of JSON objects. This is great for processing,
122 but not for reading directly. A **`bunyan` tool** is provided **for
123 pretty-printing bunyan logs** and for **filtering** (e.g.
124 `| bunyan -c 'this.foo == "bar"'`). Using our example above:
125
126 $ node hi.js | ./bin/bunyan
127 [2013-01-04T19:01:18.241Z] INFO: myapp/40208 on banana.local: hi
128 [2013-01-04T19:01:18.242Z] WARN: myapp/40208 on banana.local: au revoir (lang=fr)
129
130 See the screenshot above for an example of the default coloring of rendered
131 log output. That example also shows the nice formatting automatically done for
132 some well-known log record fields (e.g. `req` is formatted like an HTTP request,
133 `res` like an HTTP response, `err` like an error stack trace).
134
135 One interesting feature is **filtering** of log content, which can be useful
136 for digging through large log files or for analysis. We can filter only
137 records above a certain level:
138
139 $ node hi.js | bunyan -l warn
140 [2013-01-04T19:08:37.182Z] WARN: myapp/40353 on banana.local: au revoir (lang=fr)
141
142 Or filter on the JSON fields in the records (e.g. only showing the French
143 records in our contrived example):
144
145 $ node hi.js | bunyan -c 'this.lang == "fr"'
146 [2013-01-04T19:08:26.411Z] WARN: myapp/40342 on banana.local: au revoir (lang=fr)
aa166b2 @trentm first stab. 'log.info(...)'
authored
147
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
148 See `bunyan --help` for other facilities.
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
149
150
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
151 ## Streams Introduction
b3bd83c @trentm some intro docs
authored
152
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
153 By default, log output is to stdout and at the "info" level. Explicitly that
154 looks like:
155
156 var log = bunyan.createLogger({
157 name: 'myapp',
158 stream: process.stdout,
159 level: 'info'
160 });
b3bd83c @trentm some intro docs
authored
161
7cb505c @notmatt Typo.
notmatt authored
162 That is an abbreviated form for a single stream. **You can define multiple
44d280d @trentm add TRACE level (use for external libraries). Also, some doc updates.
authored
163 streams at different levels**.
b3bd83c @trentm some intro docs
authored
164
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
165 var log = bunyan.createLogger({
166 name: 'myapp',
b3bd83c @trentm some intro docs
authored
167 streams: [
168 {
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
169 level: 'info',
f3e0ba6 @alexanderGugel fix typo
alexanderGugel authored
170 stream: process.stdout // log INFO and above to stdout
b3bd83c @trentm some intro docs
authored
171 },
172 {
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
173 level: 'error',
1ed684d @trentm Ensure a top-level `level` given in `bunyan.createLogger` is *used* f…
authored
174 path: '/var/tmp/myapp-error.log' // log ERROR and above to a file
b3bd83c @trentm some intro docs
authored
175 }
176 ]
177 });
178
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
179 More on streams in the [Streams section](#streams) below.
18c6fc6 @trentm docs on streams
authored
180
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
181
182 ## log.child
183
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
184 Bunyan has a concept of a child logger to **specialize a logger for a
185 sub-component of your application**, i.e. to create a new logger with
186 additional bound fields that will be included in its log records. A child
187 logger is created with `log.child(...)`.
fb1ed4f @trentm TODOne
authored
188
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
189 In the following example, logging on a "Wuzzle" instance's `this.log` will
190 be exactly as on the parent logger with the addition of the `widget_type`
191 field:
fb1ed4f @trentm TODOne
authored
192
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
193 var bunyan = require('bunyan');
194 var log = bunyan.createLogger({name: 'myapp'});
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
195
fb1ed4f @trentm TODOne
authored
196 function Wuzzle(options) {
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
197 this.log = options.log.child({widget_type: 'wuzzle'});
198 this.log.info('creating a wuzzle')
fb1ed4f @trentm TODOne
authored
199 }
200 Wuzzle.prototype.woos = function () {
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
201 this.log.warn('This wuzzle is woosey.')
fb1ed4f @trentm TODOne
authored
202 }
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
203
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
204 log.info('start');
205 var wuzzle = new Wuzzle({log: log});
fb1ed4f @trentm TODOne
authored
206 wuzzle.woos();
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
207 log.info('done');
208
209 Running that looks like (raw):
210
211 $ node myapp.js
212 {"name":"myapp","hostname":"myhost","pid":34572,"level":30,"msg":"start","time":"2013-01-04T07:47:25.814Z","v":0}
213 {"name":"myapp","hostname":"myhost","pid":34572,"widget_type":"wuzzle","level":30,"msg":"creating a wuzzle","time":"2013-01-04T07:47:25.815Z","v":0}
214 {"name":"myapp","hostname":"myhost","pid":34572,"widget_type":"wuzzle","level":40,"msg":"This wuzzle is woosey.","time":"2013-01-04T07:47:25.815Z","v":0}
215 {"name":"myapp","hostname":"myhost","pid":34572,"level":30,"msg":"done","time":"2013-01-04T07:47:25.816Z","v":0}
b3bd83c @trentm some intro docs
authored
216
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
217 And with the `bunyan` CLI (using the "short" output mode):
218
219 $ node myapp.js | bunyan -o short
220 07:46:42.707Z INFO myapp: start
221 07:46:42.709Z INFO myapp: creating a wuzzle (widget_type=wuzzle)
222 07:46:42.709Z WARN myapp: This wuzzle is woosey. (widget_type=wuzzle)
223 07:46:42.709Z INFO myapp: done
224
225
226 A more practical example is in the
227 [node-restify](https://github.com/mcavage/node-restify) web framework.
228 Restify uses Bunyan for its logging. One feature of its integration, is that
d10f9ec @trentm update notes on req_id for restify 2.x changes
authored
229 if `server.use(restify.requestLogger())` is used, each restify request handler
230 includes a `req.log` logger that is:
40777aa @trentm 'log.child(..., true)' support for 10x faster with 'simple' field add…
authored
231
232 log.child({req_id: <unique request id>}, true)
233
234 Apps using restify can then use `req.log` and have all such log records
d10f9ec @trentm update notes on req_id for restify 2.x changes
authored
235 include the unique request id (as "req\_id"). Handy.
40777aa @trentm 'log.child(..., true)' support for 10x faster with 'simple' field add…
authored
236
237
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
238 ## Serializers
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
239
240 Bunyan has a concept of **"serializers" to produce a JSON-able object from a
c8fe8da @trentm tyop. update to latest cutarelease tool
authored
241 JavaScript object**, so you can easily do the following:
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
242
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
243 log.info({req: <request object>}, 'something about handling this request');
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
244
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
245 Serializers is a mapping of log record field name, "req" in this example, to
246 a serializer function. That looks like this:
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
247
248 function reqSerializer(req) {
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
249 return {
250 method: req.method,
251 url: req.url,
252 headers: req.headers
253 }
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
254 }
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
255 var log = bunyan.createLogger({
256 name: 'myapp',
257 serializers: {
258 req: reqSerializer
259 }
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
260 });
261
262 Or this:
263
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
264 var log = bunyan.createLogger({
265 name: 'myapp',
266 serializers: {req: bunyan.stdSerializers.req}
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
267 });
268
78826c5 @cb1kenobi Fixed typo in the readme.
cb1kenobi authored
269 because Bunyan includes a small set of standard serializers. To use all the
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
270 standard serializers you can use:
271
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
272 var log = bunyan.createLogger({
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
273 ...
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
274 serializers: bunyan.stdSerializers
947e46f @trentm start serializers support. Add 'req' standard serializer. You can add…
authored
275 });
193120a @trentm "paul" cuteness was annoying me for this
authored
276
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
277 **Note**: Your own serializers should never throw, otherwise you'll get an
8eb2abd @trentm update readme for serializers
authored
278 ugly message on stderr from Bunyan (along with the traceback) and the field
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
279 in your log record will be replaced with a short error message.
280
8eb2abd @trentm update readme for serializers
authored
281
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
282 ## src
283
9feb9c8 @trentm CLI file args: bunyan foo.log bar.log
authored
284 The **source file, line and function of the log call site** can be added to
285 log records by using the `src: true` config option:
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
286
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
287 var log = bunyan.createLogger({src: true, ...});
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
288
289 This adds the call source info with the 'src' field, like this:
290
291 {
140c9fd @trentm s/service/name/ for Logger name field. "service" is unnecessarily tie…
authored
292 "name": "src-example",
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
293 "hostname": "banana.local",
bdc55f0 @trentm issue #10: correct readme examples to have the requisite 'pid' field
authored
294 "pid": 123,
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
295 "component": "wuzzle",
296 "level": 4,
297 "msg": "This wuzzle is woosey.",
298 "time": "2012-02-06T04:19:35.605Z",
299 "src": {
300 "file": "/Users/trentm/tm/node-bunyan/examples/src.js",
301 "line": 20,
302 "func": "Wuzzle.woos"
303 },
304 "v": 0
305 }
8eb2abd @trentm update readme for serializers
authored
306
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
307 **WARNING: Determining the call source info is slow. Never use this option
308 in production.**
193120a @trentm "paul" cuteness was annoying me for this
authored
309
aa166b2 @trentm first stab. 'log.info(...)'
authored
310
311 # Levels
312
02b5863 @trentm clarify log level best practices
authored
313 The log levels in bunyan are as follows. The level descriptions are best
314 practice *opinions*.
315
316 - "fatal" (60): The service/app is going to stop or become unusable now.
317 An operator should definitely look into this soon.
318 - "error" (50): Fatal for a particular request, but the service/app continues
319 servicing other requests. An operator should look at this soon(ish).
320 - "warn" (40): A note on something that should probably be looked at by an
321 operator eventually.
322 - "info" (30): Detail on regular operation.
323 - "debug" (20): Anything else, i.e. too verbose to be included in "info" level.
324 - "trace" (10): Logging from external libraries used by your app or *very*
325 detailed application logging.
326
327 Suggestions: Use "debug" sparingly. Information that will be useful to debug
328 errors *post mortem* should usually be included in "info" messages if it's
329 generally relevant or else with the corresponding "error" event. Don't rely
330 on spewing mostly irrelevant debug messages all the time and sifting through
331 them when an error occurs.
44d280d @trentm add TRACE level (use for external libraries). Also, some doc updates.
authored
332
9feb9c8 @trentm CLI file args: bunyan foo.log bar.log
authored
333 Integers are used for the actual level values (10 for "trace", ..., 60 for
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
334 "fatal") and constants are defined for the (bunyan.TRACE ... bunyan.DEBUG).
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
335 The lowercase level names are aliases supported in the API.
aa166b2 @trentm first stab. 'log.info(...)'
authored
336
352c417 @trentm Add `log.level(...)` and `log.levels(...)` API for changing logger st…
authored
337 Here is the API for changing levels in an existing logger:
338
339 log.level() -> INFO // gets current level (lowest level of all streams)
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
340
352c417 @trentm Add `log.level(...)` and `log.levels(...)` API for changing logger st…
authored
341 log.level(INFO) // set all streams to level INFO
342 log.level("info") // set all streams to level INFO
343
344 log.levels() -> [DEBUG, INFO] // get array of levels of all streams
345 log.levels(0) -> DEBUG // get level of stream at index 0
346 log.levels("foo") // get level of stream with name "foo"
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
347
352c417 @trentm Add `log.level(...)` and `log.levels(...)` API for changing logger st…
authored
348 log.levels(0, INFO) // set level of stream 0 to INFO
349 log.levels(0, "info") // can use "info" et al aliases
350 log.levels("foo", WARN) // set stream named "foo" to WARN
351
352
aa166b2 @trentm first stab. 'log.info(...)'
authored
353
354 # Log Record Fields
355
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
356 This section will describe *rules* for the Bunyan log format: field names,
357 field meanings, required fields, etc. However, a Bunyan library doesn't
358 strictly enforce all these rules while records are being emitted. For example,
359 Bunyan will add a `time` field with the correct format to your log records,
360 but you can specify your own. It is the caller's responsibility to specify
361 the appropriate format.
b3bd83c @trentm some intro docs
authored
362
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
363 The reason for the above leniency is because IMO logging a message should
364 never break your app. This leads to this rule of logging: **a thrown
365 exception from `log.info(...)` or equivalent (other than for calling with the
366 incorrect signature) is always a bug in Bunyan.**
367
368
369 A typical Bunyan log record looks like this:
370
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
371 {"name":"myserver","hostname":"banana.local","pid":123,"req":{"method":"GET","url":"/path?q=1#anchor","headers":{"x-hi":"Mom","connection":"close"}},"level":3,"msg":"start request","time":"2012-02-03T19:02:46.178Z","v":0}
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
372
373 Pretty-printed:
374
375 {
140c9fd @trentm s/service/name/ for Logger name field. "service" is unnecessarily tie…
authored
376 "name": "myserver",
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
377 "hostname": "banana.local",
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
378 "pid": 123,
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
379 "req": {
380 "method": "GET",
381 "url": "/path?q=1#anchor",
382 "headers": {
383 "x-hi": "Mom",
384 "connection": "close"
385 },
386 "remoteAddress": "120.0.0.1",
387 "remotePort": 51244
388 },
389 "level": 3,
390 "msg": "start request",
391 "time": "2012-02-03T19:02:57.534Z",
392 "v": 0
393 }
394
395
396 Core fields:
397
0a703ea replacing "Bunion" with "Bunyan" because they're not the same thing
Noah H. Smith authored
398 - `v`: Required. Integer. Added by Bunyan. Cannot be overriden.
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
399 This is the Bunyan log format version (`require('bunyan').LOG_VERSION`).
400 The log version is a single integer. `0` is until I release a version
401 "1.0.0" of node-bunyan. Thereafter, starting with `1`, this will be
402 incremented if there is any backward incompatible change to the log record
403 format. Details will be in "CHANGES.md" (the change log).
0a703ea replacing "Bunion" with "Bunyan" because they're not the same thing
Noah H. Smith authored
404 - `level`: Required. Integer. Added by Bunyan. Cannot be overriden.
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
405 See the "Levels" section.
140c9fd @trentm s/service/name/ for Logger name field. "service" is unnecessarily tie…
authored
406 - `name`: Required. String. Provided at Logger creation.
407 You must specify a name for your logger when creating it. Typically this
408 is the name of the service/app using Bunyan for logging.
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
409 - `hostname`: Required. String. Provided or determined at Logger creation.
410 You can specify your hostname at Logger creation or it will be retrieved
411 vi `os.hostname()`.
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
412 - `pid`: Required. Integer. Filled in automatically at Logger creation.
0a703ea replacing "Bunion" with "Bunyan" because they're not the same thing
Noah H. Smith authored
413 - `time`: Required. String. Added by Bunyan. Can be overriden.
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
414 The date and time of the event in [ISO 8601
415 Extended Format](http://en.wikipedia.org/wiki/ISO_8601) format and in UTC,
416 as from
417 [`Date.toISOString()`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/toISOString).
418 - `msg`: Required. String.
419 Every `log.debug(...)` et al call must provide a log message.
e934baf @trentm v0.4: add 'src' call source location info support (the Yunong release)
authored
420 - `src`: Optional. Object giving log call source info. This is added
421 automatically by Bunyan if the "src: true" config option is given to the
422 Logger. Never use in production as this is really slow.
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
423
424
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
425 Go ahead and add more fields, and nested ones are fine (and recommended) as
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
426 well. This is why we're using JSON. Some suggestions and best practices
427 follow (feedback from actual users welcome).
428
429
430 Recommended/Best Practice Fields:
431
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
432 - `err`: Object. A caught JS exception. Log that thing with `log.info(err)`
543ef15 @trentm 'log.info(err)' support
authored
433 to get:
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
434
543ef15 @trentm 'log.info(err)' support
authored
435 ...
436 "err": {
437 "message": "boom",
438 "name": "TypeError",
439 "stack": "TypeError: boom\n at Object.<anonymous> ..."
440 },
441 "msg": "boom",
442 ...
443
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
444 Or use the `bunyan.stdSerializers.err` serializer in your Logger and
543ef15 @trentm 'log.info(err)' support
authored
445 do this `log.error({err: err}, "oops")`. See "examples/err.js".
446
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
447 - `req_id`: String. A request identifier. Including this field in all logging
448 tied to handling a particular request to your server is strongly suggested.
449 This allows post analysis of logs to easily collate all related logging
450 for a request. This really shines when you have a SOA with multiple services
451 and you carry a single request ID from the top API down through all APIs
452 (as [node-restify](https://github.com/mcavage/node-restify) facilitates
d10f9ec @trentm update notes on req_id for restify 2.x changes
authored
453 with its 'Request-Id' header).
543ef15 @trentm 'log.info(err)' support
authored
454
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
455 - `req`: An HTTP server request. Bunyan provides `bunyan.stdSerializers.req`
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
456 to serialize a request with a suggested set of keys. Example:
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
457
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
458 {
459 "method": "GET",
460 "url": "/path?q=1#anchor",
461 "headers": {
462 "x-hi": "Mom",
463 "connection": "close"
464 },
465 "remoteAddress": "120.0.0.1",
466 "remotePort": 51244
467 }
468
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
469 - `res`: An HTTP server response. Bunyan provides `bunyan.stdSerializers.res`
c12a90a @trentm issue #4: add 'pid' automatic log record field
authored
470 to serialize a response with a suggested set of keys. Example:
a475a1a @trentm 0.2: specing core log record fields (mainly)
authored
471
472 {
473 "statusCode": 200,
474 "header": "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nConnection: keep-alive\r\nTransfer-Encoding: chunked\r\n\r\n"
475 }
476
477
478 Other fields to consider:
479
480 - `req.username`: Authenticated user (or for a 401, the user attempting to
481 auth).
482 - Some mechanism to calculate response latency. "restify" users will have
483 a "X-Response-Time" header. A `latency` custom field would be fine.
484 - `req.body`: If you know that request bodies are small (common in APIs,
485 for example), then logging the request body is good.
b3bd83c @trentm some intro docs
authored
486
aa166b2 @trentm first stab. 'log.info(...)'
authored
487
44d280d @trentm add TRACE level (use for external libraries). Also, some doc updates.
authored
488 # Streams
489
18c6fc6 @trentm docs on streams
authored
490 A "stream" is Bunyan's name for an output for log messages (the equivalent
491 to a log4j Appender). Ultimately Bunyan uses a
44d280d @trentm add TRACE level (use for external libraries). Also, some doc updates.
authored
492 [Writable Stream](http://nodejs.org/docs/latest/api/all.html#writable_Stream)
18c6fc6 @trentm docs on streams
authored
493 interface, but there are some additional attributes used to create and
494 manage the stream. A Bunyan Logger instance has one or more streams.
8b3bdef @trentm readme tweaks
authored
495 In general streams are specified with the "streams" option:
18c6fc6 @trentm docs on streams
authored
496
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
497 var bunyan = require('bunyan');
498 var log = bunyan.createLogger({
499 name: "foo",
500 streams: [
501 {
502 stream: process.stderr,
503 level: "debug"
504 },
505 ...
506 ]
507 });
18c6fc6 @trentm docs on streams
authored
508
509 For convenience, if there is only one stream, it can specified with the
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
510 "stream" and "level" options (internally converted to a `Logger.streams`).
18c6fc6 @trentm docs on streams
authored
511
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
512 var log = bunyan.createLogger({
513 name: "foo",
514 stream: process.stderr,
515 level: "debug"
516 });
18c6fc6 @trentm docs on streams
authored
517
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
518 Note that "file" streams do not support this shortcut (partly for historical
519 reasons and partly to not make it difficult to add a literal "path" field
520 on log records).
18c6fc6 @trentm docs on streams
authored
521
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
522 If neither "streams" nor "stream" are specified, the default is a stream of
523 type "stream" emitting to `process.stdout` at the "info" level.
18c6fc6 @trentm docs on streams
authored
524
525
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
526 ## stream errors
18c6fc6 @trentm docs on streams
authored
527
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
528 Bunyan re-emits error events from the created `WriteStream`. So you can
529 do this:
37a1447 @trentm per issue #8 change the way a raw stream is handled
authored
530
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
531 var log = bunyan.createLogger({name: 'mylog', streams: [{path: LOG_PATH}]});
532 log.on('error', function (err, stream) {
533 // Handle stream write or create error here.
534 });
18c6fc6 @trentm docs on streams
authored
535
6cdcbf4 @trentm attempt to clarify error *events*, per #124
authored
536 Note: This is **not** that same as a log record at the "error" level as
537 produced by `log.error(...)`.
538
44d280d @trentm add TRACE level (use for external libraries). Also, some doc updates.
authored
539
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
540 ## stream type: `stream`
7931359 @trentm pull #21: tweak readme
authored
541
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
542 A `type === 'stream'` is a plain ol' node.js [Writable
543 Stream](http://nodejs.org/docs/latest/api/all.html#writable_Stream). A
544 "stream" (the writeable stream) field is required. E.g.: `process.stdout`,
545 `process.stderr`.
546
547 var log = bunyan.createLogger({
548 name: 'foo',
549 streams: [{
550 stream: process.stderr
551 // `type: 'stream'` is implied
552 }]
553 });
554
555 <table>
556 <tr>
557 <th>Field</th>
558 <th>Required?</th>
559 <th>Default</th>
560 <th>Description</th>
561 </tr>
562 <tr>
563 <td>stream</td>
564 <td>Yes</td>
565 <td>-</td>
566 <td>A "Writable Stream", e.g. a std handle or an open file write stream.</td>
567 </tr>
568 <tr>
569 <td>type</td>
570 <td>No</td>
571 <td>n/a</td>
572 <td>`type == 'stream'` is implied if the `stream` field is given.</td>
573 </tr>
574 <tr>
575 <td>level</td>
576 <td>No</td>
577 <td>info</td>
578 <td>The level at which logging to this stream is enabled. If not
579 specified it defaults to "info". If specified this can be one of the
580 level strings ("trace", "debug", ...) or constants (`bunyan.TRACE`,
581 `bunyan.DEBUG`, ...).</td>
582 </tr>
583 <tr>
584 <td>name</td>
585 <td>No</td>
586 <td>-</td>
587 <td>A name for this stream. This may be useful for usage of `log.level(NAME,
588 LEVEL)`. See the [Levels section](#levels) for details. A stream "name" isn't
589 used for anything else.</td>
590 </tr>
591 </table>
592
593
594 ## stream type: `file`
595
596 A `type === 'file'` stream requires a "path" field. Bunyan will open this
597 file for appending. E.g.:
598
599 var log = bunyan.createLogger({
600 name: 'foo',
601 streams: [{
602 path: '/var/log/foo.log',
603 // `type: 'file'` is implied
604 }]
605 });
606
607 <table>
608 <tr>
609 <th>Field</th>
610 <th>Required?</th>
611 <th>Default</th>
612 <th>Description</th>
613 </tr>
614 <tr>
615 <td>path</td>
616 <td>Yes</td>
617 <td>-</td>
618 <td>A file path to which to log.</td>
619 </tr>
620 <tr>
621 <td>type</td>
622 <td>No</td>
623 <td>n/a</td>
624 <td>`type == 'file'` is implied if the `path` field is given.</td>
625 </tr>
626 <tr>
627 <td>level</td>
628 <td>No</td>
629 <td>info</td>
630 <td>The level at which logging to this stream is enabled. If not
631 specified it defaults to "info". If specified this can be one of the
632 level strings ("trace", "debug", ...) or constants (`bunyan.TRACE`,
633 `bunyan.DEBUG`, ...).</td>
634 </tr>
635 <tr>
636 <td>name</td>
637 <td>No</td>
638 <td>-</td>
639 <td>A name for this stream. This may be useful for usage of `log.level(NAME,
640 LEVEL)`. See the [Levels section](#levels) for details. A stream "name" isn't
641 used for anything else.</td>
642 </tr>
643 </table>
644
645
646 ## stream type: `rotating-file`
647
2c2459d @trentm #117 add warning about using rotating-file and cluster together
authored
648 **WARNING on node 0.8 usage:** Users of Bunyan's `rotating-file` should (a) be
649 using at least bunyan 0.23.1 (with the fix for [this
4670906 @trentm skip rotating-file test on node 0.8; warn about rotating-file issues
authored
650 issue](https://github.com/trentm/node-bunyan/pull/97)), and (b) should use at
651 least node 0.10 (node 0.8 does not support the `unref()` method on
652 `setTimeout(...)` needed for the mentioned fix). The symptom is that process
653 termination will hang for up to a full rotation period.
654
2c2459d @trentm #117 add warning about using rotating-file and cluster together
authored
655 **WARNING on [cluster](http://nodejs.org/docs/latest/api/all.html#all_cluster)
656 usage:** Using Bunyan's `rotating-file` stream with node.js's "cluster" module
657 can result in unexpected file rotation. You must not have multiple processes
658 in the cluster logging to the same file path. In other words, you must have
659 a separate log file path for the master and each worker in the cluster.
660 Alternatively, consider using a system file rotation facility such as
661 `logrotate` on Linux or `logadm` on SmartOS/Illumos. See
662 [this comment on issue #117](https://github.com/trentm/node-bunyan/issues/117#issuecomment-44804938)
663 for details.
4670906 @trentm skip rotating-file test on node 0.8; warn about rotating-file issues
authored
664
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
665 A `type === 'rotating-file'` is a file stream that handles file automatic
666 rotation.
667
668 var log = bunyan.createLogger({
669 name: 'foo',
670 streams: [{
671 type: 'rotating-file',
672 path: '/var/log/foo.log',
673 period: '1d', // daily rotation
674 count: 3 // keep 3 back copies
675 }]
676 });
677
678 This will rotate '/var/log/foo.log' every day (at midnight) to:
679
680 /var/log/foo.log.0 # yesterday
681 /var/log/foo.log.1 # 1 day ago
682 /var/log/foo.log.2 # 2 days ago
683
684 *Currently*, there is no support for providing a template for the rotated
685 files, or for rotating when the log reaches a threshold size.
686
687 <table>
688 <tr>
689 <th>Field</th>
690 <th>Required?</th>
691 <th>Default</th>
692 <th>Description</th>
693 </tr>
694 <tr>
695 <td>type</td>
696 <td>Yes</td>
697 <td>-</td>
698 <td>"rotating-file"</td>
699 </tr>
700 <tr>
701 <td>path</td>
702 <td>Yes</td>
703 <td>-</td>
704 <td>A file path to which to log. Rotated files will be "$path.0",
705 "$path.1", ...</td>
706 </tr>
707 <tr>
708 <td>period</td>
709 <td>No</td>
710 <td>1d</td>
711 <td>The period at which to rotate. This is a string of the format
d41f15b @trentm A follow-up to #250 to indicate the 'ms' log rotation scope is just f…
authored
712 "$number$scope" where "$scope" is one of "ms" (milliseconds -- only useful for
713 testing), "h" (hours), "d" (days), "w" (weeks), "m" (months), "y" (years). Or
714 one of the following names can be used "hourly" (means 1h), "daily" (1d),
715 "weekly" (1w), "monthly" (1m), "yearly" (1y). Rotation is done at the start of
716 the scope: top of the hour (h), midnight (d), start of Sunday (w), start of the
717 1st of the month (m), start of Jan 1st (y).</td>
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
718 </tr>
719 <tr>
720 <td>count</td>
721 <td>No</td>
722 <td>10</td>
723 <td>The number of rotated files to keep.</td>
724 </tr>
725 <tr>
726 <td>level</td>
727 <td>No</td>
728 <td>info</td>
729 <td>The level at which logging to this stream is enabled. If not
730 specified it defaults to "info". If specified this can be one of the
731 level strings ("trace", "debug", ...) or constants (`bunyan.TRACE`,
732 `bunyan.DEBUG`, ...).</td>
733 </tr>
734 <tr>
735 <td>name</td>
736 <td>No</td>
737 <td>-</td>
738 <td>A name for this stream. This may be useful for usage of `log.level(NAME,
739 LEVEL)`. See the [Levels section](#levels) for details. A stream "name" isn't
740 used for anything else.</td>
741 </tr>
742 </table>
743
744
eac13c0 @trentm issue #104: `log.reopenFileStreams()` convenience method to be used w…
authored
745 **Note on log rotation**: Often you may be using external log rotation utilities
746 like `logrotate` on Linux or `logadm` on SmartOS/Illumos. In those cases, unless
747 your are ensuring "copy and truncate" sematics (via `copytruncate` with
748 logrotate or `-c` with logadm) then the fd for your 'file' stream will change.
749 You can tell bunyan to reopen the file stream with code like this in your
750 app:
751
752 var log = bunyan.createLogger(...);
753 ...
754 process.on('SIGUSR2', function () {
755 log.reopenFileStreams();
756 });
757
758 where you'd configure your log rotation to send SIGUSR2 (or some other signal)
759 to your process. Any other mechanism to signal your app to run
760 `log.reopenFileStreams()` would work as well.
761
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
762
763 ## stream type: `raw`
44d280d @trentm add TRACE level (use for external libraries). Also, some doc updates.
authored
764
37a1447 @trentm per issue #8 change the way a raw stream is handled
authored
765 - `raw`: Similar to a "stream" writeable stream, except that the write method
766 is given raw log record *Object*s instead of a JSON-stringified string.
767 This can be useful for hooking on further processing to all Bunyan logging:
768 pushing to an external service, a RingBuffer (see below), etc.
769
770
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
771
772 ## `raw` + RingBuffer Stream
37a1447 @trentm per issue #8 change the way a raw stream is handled
authored
773
f1996fc @davepacheco add ring buffer stream
davepacheco authored
774 Bunyan comes with a special stream called a RingBuffer which keeps the last N
775 records in memory and does *not* write the data anywhere else. One common
776 strategy is to log 'info' and higher to a normal log file but log all records
777 (including 'trace') to a ringbuffer that you can access via a debugger, or your
778 own HTTP interface, or a post-mortem facility like MDB or node-panic.
779
780 To use a RingBuffer:
781
1eed1fa @trentm use RingBuffer.records instead of RingBuffer.enties (related to pull …
authored
782 /* Create a ring buffer that stores the last 100 records. */
f1996fc @davepacheco add ring buffer stream
davepacheco authored
783 var bunyan = require('bunyan');
784 var ringbuffer = new bunyan.RingBuffer({ limit: 100 });
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
785 var log = bunyan.createLogger({
37a1447 @trentm per issue #8 change the way a raw stream is handled
authored
786 name: 'foo',
787 streams: [
788 {
789 level: 'info',
790 stream: process.stdout
791 },
792 {
793 level: 'trace',
794 type: 'raw', // use 'raw' to get raw log record objects
795 stream: ringbuffer
796 }
797 ]
f1996fc @davepacheco add ring buffer stream
davepacheco authored
798 });
799
800 log.info('hello world');
1eed1fa @trentm use RingBuffer.records instead of RingBuffer.enties (related to pull …
authored
801 console.log(ringbuffer.records);
f1996fc @davepacheco add ring buffer stream
davepacheco authored
802
803 This example emits:
804
805 [ { name: 'foo',
806 hostname: '912d2b29',
807 pid: 50346,
808 level: 30,
809 msg: 'hello world',
810 time: '2012-06-19T21:34:19.906Z',
811 v: 0 } ]
812
44d280d @trentm add TRACE level (use for external libraries). Also, some doc updates.
authored
813
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
814 ## third-party streams
815
6ed1afd @trentm readme note
authored
816 (There are a lot that aren't listed here. `npm search bunyan` is a good
817 place to start.)
818
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
819 - syslog:
820 [mcavage/node-bunyan-syslog](https://github.com/mcavage/node-bunyan-syslog)
821 provides support for directing bunyan logging to a syslog server.
822
3d786a8 @sethpollack add third-party stream for slack
sethpollack authored
823 - bunyan-slack:
824 [qualitybath/bunyan-slack](https://github.com/qualitybath/bunyan-slack) Bunyan stream for Slack chat integration.
825
ef669b6 @sethpollack add third-party stream for fogbugz
sethpollack authored
826 - bunyan-fogbugz
827 [qualitybath/bunyan-fogbugz](https://github.com/qualitybath/bunyan-fogbugz) Bunyan stream for sending automated crash reports to FogBugz
828
7a88401 @mirkokiefer add bunyan-cloudwatch to readme
mirkokiefer authored
829 - bunyan-cloudwatch:
830 [mirkokiefer/bunyan-cloudwatch](https://github.com/mirkokiefer/bunyan-cloudwatch) Bunyan stream for sending logs to AWS CloudWatch.
831
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
832 - TODO: eventually https://github.com/trentm/node-bunyan-winston
833
834
835
96e2a9b @trentm runtime log snooping as a name sugegstion from dap for bunyan -p
authored
836 # Runtime log snooping via DTrace
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
837
dacdd08 @trentm add note about separate dtrace-provider installation necessity
authored
838 **Note**: To use Bunyan's DTrace facilities you need to manually install
839 the "dtrace-provider" lib separately via `npm install dtrace-provider`.
840
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
841 On systems that support DTrace (e.g., MacOS, FreeBSD, illumos derivatives
842 like SmartOS and OmniOS), Bunyan will create a DTrace provider (`bunyan`)
843 that makes available the following probes:
844
845 log-trace
846 log-debug
847 log-info
848 log-warn
849 log-error
850 log-fatal
851
8732764 @trentm issue #48: changelog, add Bryan to AUTHORS, basic dtrace test suite
authored
852 Each of these probes has a single argument: the string that would be
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
853 written to the log. Note that when a probe is enabled, it will
854 fire whenever the corresponding function is called, even if the level of
855 the log message is less than that of any stream.
856
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
857
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
858 ## DTrace examples
859
8732764 @trentm issue #48: changelog, add Bryan to AUTHORS, basic dtrace test suite
authored
860 Trace all log messages coming from any Bunyan module on the system.
861 (The `-x strsize=4k` is to raise dtrace's default 256 byte buffer size
862 because log messages are longer than typical dtrace probes.)
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
863
8732764 @trentm issue #48: changelog, add Bryan to AUTHORS, basic dtrace test suite
authored
864 dtrace -x strsize=4k -qn 'bunyan*:::log-*{printf("%d: %s: %s", pid, probefunc, copyinstr(arg0))}'
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
865
866 Trace all log messages coming from the "wuzzle" component:
867
8732764 @trentm issue #48: changelog, add Bryan to AUTHORS, basic dtrace test suite
authored
868 dtrace -x strsize=4k -qn 'bunyan*:::log-*/strstr(this->str = copyinstr(arg0), "\"component\":\"wuzzle\"") != NULL/{printf("%s", this->str)}'
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
869
870 Aggregate debug messages from process 1234, by message:
871
8732764 @trentm issue #48: changelog, add Bryan to AUTHORS, basic dtrace test suite
authored
872 dtrace -x strsize=4k -n 'bunyan1234:::log-debug{@[copyinstr(arg0)] = count()}'
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
873
f08c2e6 @trentm issue #56: bunyan -p NAME
authored
874 Have the bunyan CLI pretty-print the traced logs:
875
876 dtrace -x strsize=4k -qn 'bunyan1234:::log-*{printf("%s", copyinstr(arg0))}' | bunyan
877
878 A convenience handle has been made for this:
879
880 bunyan -p 1234
881
882
8732764 @trentm issue #48: changelog, add Bryan to AUTHORS, basic dtrace test suite
authored
883 On systems that support the
884 [`jstack`](http://dtrace.org/blogs/dap/2012/04/25/profiling-node-js/) action
885 via a node.js helper, get a stack backtrace for any debug message that
886 includes the string "danger!":
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
887
8732764 @trentm issue #48: changelog, add Bryan to AUTHORS, basic dtrace test suite
authored
888 dtrace -x strsize=4k -qn 'log-debug/strstr(copyinstr(arg0), "danger!") != NULL/{printf("\n%s", copyinstr(arg0)); jstack()}'
af5a3d4 @bcantrill issue #48: add USDT DTrace support via node-dtrace-provider
bcantrill authored
889
890 Output of the above might be:
891
892 {"name":"foo","hostname":"763bf293-d65c-42d5-872b-4abe25d5c4c7.local","pid":12747,"level":20,"msg":"danger!","time":"2012-10-30T18:28:57.115Z","v":0}
893
894 node`0x87e2010
895 DTraceProviderBindings.node`usdt_fire_probe+0x32
896 DTraceProviderBindings.node`_ZN4node11DTraceProbe5_fireEN2v85LocalINS1_5ValueEEE+0x32d
897 DTraceProviderBindings.node`_ZN4node11DTraceProbe4FireERKN2v89ArgumentsE+0x77
898 << internal code >>
899 (anon) as (anon) at /root/node-bunyan/lib/bunyan.js position 40484
900 << adaptor >>
901 (anon) as doit at /root/my-prog.js position 360
902 (anon) as list.ontimeout at timers.js position 4960
903 << adaptor >>
904 << internal >>
905 << entry >>
906 node`_ZN2v88internalL6InvokeEbNS0_6HandleINS0_10JSFunctionEEENS1_INS0_6ObjectEEEiPS5_Pb+0x101
907 node`_ZN2v88internal9Execution4CallENS0_6HandleINS0_6ObjectEEES4_iPS4_Pbb+0xcb
908 node`_ZN2v88Function4CallENS_6HandleINS_6ObjectEEEiPNS1_INS_5ValueEEE+0xf0
909 node`_ZN4node12MakeCallbackEN2v86HandleINS0_6ObjectEEENS1_INS0_8FunctionEEEiPNS1_INS0_5ValueEEE+0x11f
910 node`_ZN4node12MakeCallbackEN2v86HandleINS0_6ObjectEEENS1_INS0_6StringEEEiPNS1_INS0_5ValueEEE+0x66
911 node`_ZN4node9TimerWrap9OnTimeoutEP10uv_timer_si+0x63
912 node`uv__run_timers+0x66
913 node`uv__run+0x1b
914 node`uv_run+0x17
915 node`_ZN4node5StartEiPPc+0x1d0
916 node`main+0x1b
917 node`_start+0x83
918
919 node`0x87e2010
920 DTraceProviderBindings.node`usdt_fire_probe+0x32
921 DTraceProviderBindings.node`_ZN4node11DTraceProbe5_fireEN2v85LocalINS1_5ValueEEE+0x32d
922 DTraceProviderBindings.node`_ZN4node11DTraceProbe4FireERKN2v89ArgumentsE+0x77
923 << internal code >>
924 (anon) as (anon) at /root/node-bunyan/lib/bunyan.js position 40484
925 << adaptor >>
926 (anon) as doit at /root/my-prog.js position 360
927 (anon) as list.ontimeout at timers.js position 4960
928 << adaptor >>
929 << internal >>
930 << entry >>
931 node`_ZN2v88internalL6InvokeEbNS0_6HandleINS0_10JSFunctionEEENS1_INS0_6ObjectEEEiPS5_Pb+0x101
932 node`_ZN2v88internal9Execution4CallENS0_6HandleINS0_6ObjectEEES4_iPS4_Pbb+0xcb
933 node`_ZN2v88Function4CallENS_6HandleINS_6ObjectEEEiPNS1_INS_5ValueEEE+0xf0
934 node`_ZN4node12MakeCallbackEN2v86HandleINS0_6ObjectEEENS1_INS0_8FunctionEEEiPNS1_INS0_5ValueEEE+0x11f
935 node`_ZN4node12MakeCallbackEN2v86HandleINS0_6ObjectEEENS1_INS0_6StringEEEiPNS1_INS0_5ValueEEE+0x66
936 node`_ZN4node9TimerWrap9OnTimeoutEP10uv_timer_si+0x63
937 node`uv__run_timers+0x66
938 node`uv__run+0x1b
939 node`uv_run+0x17
940 node`_ZN4node5StartEiPPc+0x1d0
941 node`main+0x1b
942 node`_start+0x83
943
944
414f335 @trentm browserify support, bump ver to 1.1.0
authored
945 # Browserify
946
947 As the [Browserify](http://browserify.org/) site says it "lets you
948 `require('modules')` in the browser by bundling up all of your dependencies."
949 It is a build tool to run on your node.js script to bundle up your script and
950 all its node.js dependencies into a single file that is runnable in the
951 browser via:
952
f5e5d57 @trentm clean up README sectioN
authored
953 <script src="play.browser.js"></script>
414f335 @trentm browserify support, bump ver to 1.1.0
authored
954
955 As of version 1.1.0, node-bunyan supports being run via Browserify. The
956 default [stream](#streams) when running in the browser is one that emits
957 raw log records to `console.log/info/warn/error`.
958
959 Here is a quick example showing you how you can get this working for your
960 script.
961
962 1. Get browserify and bunyan installed in your module:
963
964
965 $ npm install browserify bunyan
966
f5e5d57 @trentm clean up README sectioN
authored
967 2. An example script using Bunyan, "play.js":
414f335 @trentm browserify support, bump ver to 1.1.0
authored
968
f5e5d57 @trentm clean up README sectioN
authored
969 ```javascript
970 var bunyan = require('bunyan');
971 var log = bunyan.createLogger({name: 'play', level: 'debug'});
972 log.trace('this one does not emit');
973 log.debug('hi on debug'); // console.log
974 log.info('hi on info'); // console.info
975 log.warn('hi on warn'); // console.warn
976 log.error('hi on error'); // console.error
977 ```
978
979 3. Build this into a bundle to run in the browser, "play.browser.js":
980
981 $ ./node_modules/.bin/browserify play.js -o play.browser.js
982
983 4. Put that into an HTML file, "play.html":
984
985 ```html
986 <!DOCTYPE html>
987 <html>
988 <head>
989 <meta charset="utf-8">
990 <script src="play.browser.js"></script>
991 </head>
992 <body>
993 <div>hi</div>
994 </body>
995 </html>
996 ```
414f335 @trentm browserify support, bump ver to 1.1.0
authored
997
998 5. Open that in your browser and open your browser console:
999
f5e5d57 @trentm clean up README sectioN
authored
1000 $ open play.html
414f335 @trentm browserify support, bump ver to 1.1.0
authored
1001
1002
1003 Here is what it looks like in Firefox's console: ![Bunyan + Browserify in the
1004 Firefox console](./docs/img/bunyan.browserify.png)
1005
f5e5d57 @trentm clean up README sectioN
authored
1006 For some, the raw log records might not be desired. To have a rendered log line
9e6a199 @trentm give people a start at rendered console.log in the browser
authored
1007 you'll want to add your own stream, starting with something like this:
1008
f5e5d57 @trentm clean up README sectioN
authored
1009 ```javascript
7c0b566 @trentm [issue #210] Export `bunyan.nameFromLevel` and `bunyan.levelFromName`
authored
1010 var bunyan = require('./lib/bunyan');
1011
f5e5d57 @trentm clean up README sectioN
authored
1012 function MyRawStream() {}
1013 MyRawStream.prototype.write = function (rec) {
7c0b566 @trentm [issue #210] Export `bunyan.nameFromLevel` and `bunyan.levelFromName`
authored
1014 console.log('[%s] %s: %s',
1015 rec.time.toISOString(),
1016 bunyan.nameFromLevel[rec.level],
1017 rec.msg);
f5e5d57 @trentm clean up README sectioN
authored
1018 }
1019
1020 var log = bunyan.createLogger({
1021 name: 'play',
1022 streams: [
1023 {
1024 level: 'info',
1025 stream: new MyRawStream(),
1026 type: 'raw'
7c0b566 @trentm [issue #210] Export `bunyan.nameFromLevel` and `bunyan.levelFromName`
authored
1027 }
f5e5d57 @trentm clean up README sectioN
authored
1028 ]
1029 });
9e6a199 @trentm give people a start at rendered console.log in the browser
authored
1030
f5e5d57 @trentm clean up README sectioN
authored
1031 log.info('hi on info');
1032 ```
9e6a199 @trentm give people a start at rendered console.log in the browser
authored
1033
1034
414f335 @trentm browserify support, bump ver to 1.1.0
authored
1035
1036
2fe6983 @trentm versioning scheme
authored
1037 # Versioning
1038
1039 The scheme I follow is most succintly described by the bootstrap guys
02b5863 @trentm clarify log level best practices
authored
1040 [here](https://github.com/twitter/bootstrap#versioning).
2fe6983 @trentm versioning scheme
authored
1041
79da9bb @trentm tyop
authored
1042 tl;dr: All versions are `<major>.<minor>.<patch>` which will be incremented for
2fe6983 @trentm versioning scheme
authored
1043 breaking backward compat and major reworks, new features without breaking
1044 change, and bug fixes, respectively.
1045
1046
aa166b2 @trentm first stab. 'log.info(...)'
authored
1047 # License
1048
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
1049 MIT. See "LICENSE.txt".
9786827 @trentm doc tweaks, GH-markdown workarounds
authored
1050
37a1447 @trentm per issue #8 change the way a raw stream is handled
authored
1051
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
1052 # See Also
9786827 @trentm doc tweaks, GH-markdown workarounds
authored
1053
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
1054 - Bunyan syslog support: <https://github.com/mcavage/node-bunyan-syslog>.
70ae34a @trentm mention bunyan+graylog2 supporting repo
authored
1055 - Bunyan + Graylog2: <https://github.com/mhart/gelf-stream>.
84e9e34 @trentm note express-bunyan-logger project
authored
1056 - Bunyan middleware for Express: <https://github.com/villadora/express-bunyan-logger>
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
1057 - An example of a Bunyan shim to the Winston logging system:
e8a4387 @trentm strong comparison
authored
1058 <https://github.com/trentm/node-bunyan-winston>. Also a [comparison of
1059 Winston and Bunyan](http://strongloop.com/strongblog/compare-node-js-logging-winston-bunyan/).
480ee5d @trentm log rotation support; v0.17.0; improve README docs
authored
1060 - [Bunyan for Bash](https://github.com/trevoro/bash-bunyan).
1061 - TODO: `RequestCaptureStream` example from restify.
0c09bdd @trentm note logentries connector
authored
1062 - [Bunyan integration for https://logentries.com](https://www.npmjs.org/package/logentries-stream)
Something went wrong with that request. Please try again.