UNPKG

11.8 kBHTMLView Raw
1<!DOCTYPE html>
2<html>
3<head>
4 <meta http-equiv='content-type' value='text/html;charset=utf8'>
5 <meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'>
6 <title>bunyan(1) - filter and pretty-print Bunyan log file content</title>
7 <style type='text/css' media='all'>
8 /* style: man */
9 body#manpage {margin:0}
10 .mp {max-width:100ex;padding:0 9ex 1ex 4ex}
11 .mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
12 .mp h2 {margin:10px 0 0 0}
13 .mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
14 .mp h3 {margin:0 0 0 4ex}
15 .mp dt {margin:0;clear:left}
16
17 .mp dd {margin:0 0 0 9ex}
18 .mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
19 .mp pre {margin-bottom:20px}
20 .mp pre+h2,.mp pre+h3 {margin-top:22px}
21 .mp h2+pre,.mp h3+pre {margin-top:5px}
22 .mp img {display:block;margin:auto}
23 .mp h1.man-title {display:none}
24 .mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
25 .mp h2 {font-size:16px;line-height:1.25}
26 .mp h1 {font-size:20px;line-height:2}
27 .mp {text-align:justify;background:#fff}
28 .mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
29 .mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
30 .mp u {text-decoration:underline}
31 .mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
32 .mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
33 .mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
34 .mp b.man-ref {font-weight:normal;color:#434241}
35 .mp pre {padding:0 4ex}
36 .mp pre code {font-weight:normal;color:#434241}
37 .mp h2+pre,h3+pre {padding-left:0}
38 ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
39 ol.man-decor {width:100%}
40 ol.man-decor li.tl {text-align:left}
41 ol.man-decor li.tc {text-align:center;letter-spacing:4px}
42 ol.man-decor li.tr {text-align:right;float:right}
43 </style>
44 <style type='text/css' media='all'>
45 /* style: toc */
46 .man-navigation {display:block !important;position:fixed;top:0;left:113ex;height:100%;width:100%;padding:48px 0 0 0;border-left:1px solid #dbdbdb;background:#eee}
47 .man-navigation a,.man-navigation a:hover,.man-navigation a:link,.man-navigation a:visited {display:block;margin:0;padding:5px 2px 5px 30px;color:#999;text-decoration:none}
48 .man-navigation a:hover {color:#111;text-decoration:underline}
49 </style>
50</head>
51<!--
52 The following styles are deprecated and will be removed at some point:
53 div#man, div#man ol.man, div#man ol.head, div#man ol.man.
54
55 The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
56 .man-navigation should be used instead.
57-->
58<body id='manpage'>
59 <div class='mp' id='man'>
60
61 <div class='man-navigation' style='display:none'>
62 <a href="#NAME">NAME</a>
63 <a href="#SYNOPSIS">SYNOPSIS</a>
64 <a href="#DESCRIPTION">DESCRIPTION</a>
65 <a href="#OPTIONS">OPTIONS</a>
66 <a href="#LOG-LEVELS">LOG LEVELS</a>
67 <a href="#OUTPUT-FORMATS">OUTPUT FORMATS</a>
68 <a href="#DTRACE-SUPPORT">DTRACE SUPPORT</a>
69 <a href="#ENVIRONMENT">ENVIRONMENT</a>
70 <a href="#PROJECT-BUGS">PROJECT &amp; BUGS</a>
71 <a href="#LICENSE">LICENSE</a>
72 <a href="#COPYRIGHT">COPYRIGHT</a>
73 </div>
74
75 <ol class='man-decor man-head man head'>
76 <li class='tl'>bunyan(1)</li>
77 <li class='tc'>bunyan manual</li>
78 <li class='tr'>bunyan(1)</li>
79 </ol>
80
81 <h2 id="NAME">NAME</h2>
82<p class="man-name">
83 <code>bunyan</code> - <span class="man-whatis">filter and pretty-print Bunyan log file content</span>
84</p>
85
86<h2 id="SYNOPSIS">SYNOPSIS</h2>
87
88<p><code>bunyan</code> [OPTIONS]</p>
89
90<p>... | <code>bunyan</code> [OPTIONS]</p>
91
92<p><code>bunyan</code> [OPTIONS] -p PID</p>
93
94<h2 id="DESCRIPTION">DESCRIPTION</h2>
95
96<p>"Bunyan" is <strong>a simple and fast a JSON logging library</strong> for node.js services,
97a one-JSON-object-per-line log format, and <strong>a <code>bunyan</code> CLI tool</strong> for nicely
98viewing those logs. This man page describes the latter.</p>
99
100<h3 id="Pretty-printing">Pretty-printing</h3>
101
102<p>A bunyan log file is a stream of JSON objects, optionally interspersed with
103non-JSON log lines. The primary usage of <a href="bunyan.1.html" class="man-ref">bunyan<span class="s">(1)</span></a> is to pretty print,
104for example:</p>
105
106<pre><code>$ bunyan foo.log # or `cat foo.log | bunyan
107[2012-02-08T22:56:52.856Z] INFO: myservice/123 on example.com: My message
108 extra: multi
109 line
110[2012-02-08T22:56:54.856Z] ERROR: myservice/123 on example.com: My message
111...
112</code></pre>
113
114<p>By default the "long" output format is used. Use the <code>-o FORMAT</code> option to
115emit other formats. E.g.:</p>
116
117<pre><code>$ bunyan foo.log -o short
11822:56:52.856Z INFO myservice: My message
119 extra: multi
120 line
12122:56:54.856Z ERROR myservice: My message
122...
123</code></pre>
124
125<p>These will color the output if supported in your terminal.
126See "OUTPUT FORMATS" below.</p>
127
128<h3 id="Filtering">Filtering</h3>
129
130<p>The <code>bunyan</code> CLI can also be used to filter a bunyan log. Use <code>-l LEVEL</code>
131to filter by level:</p>
132
133<pre><code>$ bunyan foo.log -l error # show only 'error' level records
134[2012-02-08T22:56:54.856Z] ERROR: myservice/123 on example.com: My message
135</code></pre>
136
137<p>Use <code>-c COND</code> to filter on a JavaScript expression returning true on the
138record data. In the COND code, <code>this</code> refers to the record object:</p>
139
140<pre><code>$ bunyan foo.log -c `this.three` # show records with the 'extra' field
141[2012-02-08T22:56:52.856Z] INFO: myservice/123 on example.com: My message
142 extra: multi
143 line
144</code></pre>
145
146<h2 id="OPTIONS">OPTIONS</h2>
147
148<dl>
149<dt><code>-h</code>, <code>--help</code></dt><dd><p>Print this help info and exit.</p></dd>
150<dt><code>--version</code></dt><dd><p>Print version of this command and exit.</p></dd>
151<dt><code>-q</code>, <code>--quiet</code></dt><dd><p>Don't warn if input isn't valid JSON.</p></dd>
152</dl>
153
154
155<p>Dtrace options (only on dtrace-supporting platforms):</p>
156
157<dl>
158<dt><code>-p PID</code>, <code>-p NAME</code></dt><dd>Process bunyan:log-* probes from the process with the given PID.
159Can be used multiple times, or specify all processes with '*',
160or a set of processes whose command &amp; args match a pattern with
161'-p NAME'.</dd>
162</dl>
163
164
165<p>Filtering options:</p>
166
167<dl>
168<dt><code>-l</code>, <code>--level LEVEL</code></dt><dd><p>Only show messages at or above the specified level. You can specify level
169<em>names</em> or numeric values. (See 'Log Levels' below.)</p></dd>
170<dt><code>-c COND</code>, <code>--condition COND</code></dt><dd><p>Run each log message through the condition and only show those that
171resolve to a truish value. E.g. <code>-c 'this.pid == 123'</code>.</p></dd>
172<dt><code>--strict</code></dt><dd><p>Suppress all but legal Bunyan JSON log lines. By default non-JSON, and
173non-Bunyan lines are passed through.</p></dd>
174</dl>
175
176
177<p>Output options:</p>
178
179<dl>
180<dt class="flush"><code>--color</code></dt><dd><p>Colorize output. Defaults to try if output stream is a TTY.</p></dd>
181<dt><code>--no-color</code></dt><dd><p>Force no coloring (e.g. terminal doesn't support it)</p></dd>
182<dt><code>-o FORMAT</code>, <code>--output FORMAT</code></dt><dd><p>Specify an output format. One of <code>long</code> (the default), <code>short</code>, <code>json</code>,
183<code>json-N</code>, <code>bunyan</code> (the native bunyan 0-indent JSON output) or <code>inspect</code>.</p></dd>
184<dt class="flush"><code>-j</code></dt><dd><p>Shortcut for <code>-o json</code>.</p></dd>
185<dt><code>-L</code>, <code>--time local</code></dt><dd><p>Display the time field in <em>local</em> time, rather than the default UTC
186time.</p></dd>
187</dl>
188
189
190<h2 id="LOG-LEVELS">LOG LEVELS</h2>
191
192<p>In Bunyan log records, then <code>level</code> field is a number. For the <code>-l|--level</code>
193argument the level <strong>names</strong> are supported as shortcuts. In <code>-c|--condition</code>
194scripts, uppercase symbols like "DEBUG" are defined for convenience.</p>
195
196<pre><code>Level Name Level Number Symbol in COND Scripts
197trace 10 TRACE
198debug 20 DEBUG
199info 30 INFO
200warn 40 WARN
201error 50 ERROR
202fatal 60 FATAL
203</code></pre>
204
205<h2 id="OUTPUT-FORMATS">OUTPUT FORMATS</h2>
206
207<pre><code>FORMAT NAME DESCRIPTION
208long (default) The default output. Long form. Colored and "pretty".
209 'req' and 'res' and 'err' fields are rendered specially
210 as an HTTP request, HTTP response and exception
211 stack trace, respectively. For backward compat, the
212 name "paul" also works for this.
213short Like the default output, but more concise. Some
214 typically redundant fields are ellided.
215json JSON output, 2-space indentation.
216json-N JSON output, N-space indentation, e.g. "json-4"
217bunyan Alias for "json-0", the Bunyan "native" format.
218inspect Node.js `util.inspect` output.
219</code></pre>
220
221<h2 id="DTRACE-SUPPORT">DTRACE SUPPORT</h2>
222
223<p>On systems that support DTrace (e.g., MacOS, FreeBSD, illumos derivatives
224like SmartOS and OmniOS), Bunyan will create a DTrace provider (<code>bunyan</code>)
225that makes available the following probes:</p>
226
227<pre><code>log-trace
228log-debug
229log-info
230log-warn
231log-error
232log-fatal
233</code></pre>
234
235<p>Each of these probes has a single argument: the string that would be
236written to the log. Note that when a probe is enabled, it will
237fire whenever the corresponding function is called, even if the level of
238the log message is less than that of any stream.</p>
239
240<p>See <a href="https://github.com/trentm/node-bunyan#dtrace-support" data-bare-link="true">https://github.com/trentm/node-bunyan#dtrace-support</a> for more details
241and the '-p PID' option above for convenience usage.</p>
242
243<h2 id="ENVIRONMENT">ENVIRONMENT</h2>
244
245<dl>
246<dt><code>BUNYAN_NO_COLOR</code></dt><dd>Set to a non-empty value to force no output coloring. See '--no-color'.</dd>
247</dl>
248
249
250<h2 id="PROJECT-BUGS">PROJECT &amp; BUGS</h2>
251
252<p><code>bunyan</code> is written in JavaScript and requires node.js (<code>node</code>). The project
253lives at <a href="https://github.com/trentm/node-bunyan" data-bare-link="true">https://github.com/trentm/node-bunyan</a> and is published to npm as
254"bunyan".</p>
255
256<ul>
257<li>README, Install notes: <a href="https://github.com/trentm/node-bunyan#readme" data-bare-link="true">https://github.com/trentm/node-bunyan#readme</a></li>
258<li>Report bugs to <a href="https://github.com/trentm/node-bunyan/issues" data-bare-link="true">https://github.com/trentm/node-bunyan/issues</a>.</li>
259<li>See the full changelog at: <a href="https://github.com/trentm/node-bunyan/blob/master/CHANGES.md" data-bare-link="true">https://github.com/trentm/node-bunyan/blob/master/CHANGES.md</a></li>
260</ul>
261
262
263<h2 id="LICENSE">LICENSE</h2>
264
265<p>MIT License (see <a href="https://github.com/trentm/node-bunyan/blob/master/LICENSE.txt" data-bare-link="true">https://github.com/trentm/node-bunyan/blob/master/LICENSE.txt</a>)</p>
266
267<h2 id="COPYRIGHT">COPYRIGHT</h2>
268
269<p>node-bunyan is Copyright (c) 2012 Joyent, Inc. Copyright (c) 2012 Trent Mick.
270All rights reserved.</p>
271
272
273 <ol class='man-decor man-foot man foot'>
274 <li class='tl'></li>
275 <li class='tc'>January 2015</li>
276 <li class='tr'>bunyan(1)</li>
277 </ol>
278
279 </div>
280<a href="https://github.com/trentm/node-bunyan"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a></body>
281</html>