236 lines
6.5 KiB
Groff
236 lines
6.5 KiB
Groff
|
.\" generated with Ronn/v0.7.3
|
||
|
|
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||
|
|
.
|
||
|
|
.TH "BUNYAN" "1" "January 2015" "" "bunyan manual"
|
||
|
|
.
|
||
|
|
.SH "NAME"
|
||
|
|
\fBbunyan\fR \- filter and pretty\-print Bunyan log file content
|
||
|
|
.
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
\fBbunyan\fR [OPTIONS]
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
\&\.\.\. | \fBbunyan\fR [OPTIONS]
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
\fBbunyan\fR [OPTIONS] \-p PID
|
||
|
|
.
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
"Bunyan" is \fBa simple and fast a JSON logging library\fR for node\.js services, a one\-JSON\-object\-per\-line log format, and \fBa \fBbunyan\fR CLI tool\fR for nicely viewing those logs\. This man page describes the latter\.
|
||
|
|
.
|
||
|
|
.SS "Pretty\-printing"
|
||
|
|
A bunyan log file is a stream of JSON objects, optionally interspersed with non\-JSON log lines\. The primary usage of bunyan(1) is to pretty print, for example:
|
||
|
|
.
|
||
|
|
.IP "" 4
|
||
|
|
.
|
||
|
|
.nf
|
||
|
|
|
||
|
|
$ bunyan foo\.log # or `cat foo\.log | bunyan
|
||
|
|
[2012\-02\-08T22:56:52\.856Z] INFO: myservice/123 on example\.com: My message
|
||
|
|
extra: multi
|
||
|
|
line
|
||
|
|
[2012\-02\-08T22:56:54\.856Z] ERROR: myservice/123 on example\.com: My message
|
||
|
|
\.\.\.
|
||
|
|
.
|
||
|
|
.fi
|
||
|
|
.
|
||
|
|
.IP "" 0
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
By default the "long" output format is used\. Use the \fB\-o FORMAT\fR option to emit other formats\. E\.g\.:
|
||
|
|
.
|
||
|
|
.IP "" 4
|
||
|
|
.
|
||
|
|
.nf
|
||
|
|
|
||
|
|
$ bunyan foo\.log \-o short
|
||
|
|
22:56:52\.856Z INFO myservice: My message
|
||
|
|
extra: multi
|
||
|
|
line
|
||
|
|
22:56:54\.856Z ERROR myservice: My message
|
||
|
|
\.\.\.
|
||
|
|
.
|
||
|
|
.fi
|
||
|
|
.
|
||
|
|
.IP "" 0
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
These will color the output if supported in your terminal\. See "OUTPUT FORMATS" below\.
|
||
|
|
.
|
||
|
|
.SS "Filtering"
|
||
|
|
The \fBbunyan\fR CLI can also be used to filter a bunyan log\. Use \fB\-l LEVEL\fR to filter by level:
|
||
|
|
.
|
||
|
|
.IP "" 4
|
||
|
|
.
|
||
|
|
.nf
|
||
|
|
|
||
|
|
$ bunyan foo\.log \-l error # show only \'error\' level records
|
||
|
|
[2012\-02\-08T22:56:54\.856Z] ERROR: myservice/123 on example\.com: My message
|
||
|
|
.
|
||
|
|
.fi
|
||
|
|
.
|
||
|
|
.IP "" 0
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
Use \fB\-c COND\fR to filter on a JavaScript expression returning true on the record data\. In the COND code, \fBthis\fR refers to the record object:
|
||
|
|
.
|
||
|
|
.IP "" 4
|
||
|
|
.
|
||
|
|
.nf
|
||
|
|
|
||
|
|
$ bunyan foo\.log \-c `this\.three` # show records with the \'extra\' field
|
||
|
|
[2012\-02\-08T22:56:52\.856Z] INFO: myservice/123 on example\.com: My message
|
||
|
|
extra: multi
|
||
|
|
line
|
||
|
|
.
|
||
|
|
.fi
|
||
|
|
.
|
||
|
|
.IP "" 0
|
||
|
|
.
|
||
|
|
.SH "OPTIONS"
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-h\fR, \fB\-\-help\fR
|
||
|
|
Print this help info and exit\.
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-\-version\fR
|
||
|
|
Print version of this command and exit\.
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-q\fR, \fB\-\-quiet\fR
|
||
|
|
Don\'t warn if input isn\'t valid JSON\.
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
Dtrace options (only on dtrace\-supporting platforms):
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-p PID\fR, \fB\-p NAME\fR
|
||
|
|
Process bunyan:log\-* probes from the process with the given PID\. Can be used multiple times, or specify all processes with \'*\', or a set of processes whose command & args match a pattern with \'\-p NAME\'\.
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
Filtering options:
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-l\fR, \fB\-\-level LEVEL\fR
|
||
|
|
Only show messages at or above the specified level\. You can specify level \fInames\fR or numeric values\. (See \'Log Levels\' below\.)
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-c COND\fR, \fB\-\-condition COND\fR
|
||
|
|
Run each log message through the condition and only show those that resolve to a truish value\. E\.g\. \fB\-c \'this\.pid == 123\'\fR\.
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-\-strict\fR
|
||
|
|
Suppress all but legal Bunyan JSON log lines\. By default non\-JSON, and non\-Bunyan lines are passed through\.
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
Output options:
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-\-color\fR
|
||
|
|
Colorize output\. Defaults to try if output stream is a TTY\.
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-\-no\-color\fR
|
||
|
|
Force no coloring (e\.g\. terminal doesn\'t support it)
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-o FORMAT\fR, \fB\-\-output FORMAT\fR
|
||
|
|
Specify an output format\. One of \fBlong\fR (the default), \fBshort\fR, \fBjson\fR, \fBjson\-N\fR, \fBbunyan\fR (the native bunyan 0\-indent JSON output) or \fBinspect\fR\.
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-j\fR
|
||
|
|
Shortcut for \fB\-o json\fR\.
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fB\-L\fR, \fB\-\-time local\fR
|
||
|
|
Display the time field in \fIlocal\fR time, rather than the default UTC time\.
|
||
|
|
.
|
||
|
|
.SH "LOG LEVELS"
|
||
|
|
In Bunyan log records, then \fBlevel\fR field is a number\. For the \fB\-l|\-\-level\fR argument the level \fBnames\fR are supported as shortcuts\. In \fB\-c|\-\-condition\fR scripts, uppercase symbols like "DEBUG" are defined for convenience\.
|
||
|
|
.
|
||
|
|
.IP "" 4
|
||
|
|
.
|
||
|
|
.nf
|
||
|
|
|
||
|
|
Level Name Level Number Symbol in COND Scripts
|
||
|
|
trace 10 TRACE
|
||
|
|
debug 20 DEBUG
|
||
|
|
info 30 INFO
|
||
|
|
warn 40 WARN
|
||
|
|
error 50 ERROR
|
||
|
|
fatal 60 FATAL
|
||
|
|
.
|
||
|
|
.fi
|
||
|
|
.
|
||
|
|
.IP "" 0
|
||
|
|
.
|
||
|
|
.SH "OUTPUT FORMATS"
|
||
|
|
.
|
||
|
|
.nf
|
||
|
|
|
||
|
|
FORMAT NAME DESCRIPTION
|
||
|
|
long (default) The default output\. Long form\. Colored and "pretty"\.
|
||
|
|
\'req\' and \'res\' and \'err\' fields are rendered specially
|
||
|
|
as an HTTP request, HTTP response and exception
|
||
|
|
stack trace, respectively\. For backward compat, the
|
||
|
|
name "paul" also works for this\.
|
||
|
|
short Like the default output, but more concise\. Some
|
||
|
|
typically redundant fields are ellided\.
|
||
|
|
json JSON output, 2\-space indentation\.
|
||
|
|
json\-N JSON output, N\-space indentation, e\.g\. "json\-4"
|
||
|
|
bunyan Alias for "json\-0", the Bunyan "native" format\.
|
||
|
|
inspect Node\.js `util\.inspect` output\.
|
||
|
|
.
|
||
|
|
.fi
|
||
|
|
.
|
||
|
|
.SH "DTRACE SUPPORT"
|
||
|
|
On systems that support DTrace (e\.g\., MacOS, FreeBSD, illumos derivatives like SmartOS and OmniOS), Bunyan will create a DTrace provider (\fBbunyan\fR) that makes available the following probes:
|
||
|
|
.
|
||
|
|
.IP "" 4
|
||
|
|
.
|
||
|
|
.nf
|
||
|
|
|
||
|
|
log\-trace
|
||
|
|
log\-debug
|
||
|
|
log\-info
|
||
|
|
log\-warn
|
||
|
|
log\-error
|
||
|
|
log\-fatal
|
||
|
|
.
|
||
|
|
.fi
|
||
|
|
.
|
||
|
|
.IP "" 0
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
Each of these probes has a single argument: the string that would be written to the log\. Note that when a probe is enabled, it will fire whenever the corresponding function is called, even if the level of the log message is less than that of any stream\.
|
||
|
|
.
|
||
|
|
.P
|
||
|
|
See \fIhttps://github\.com/trentm/node\-bunyan#dtrace\-support\fR for more details and the \'\-p PID\' option above for convenience usage\.
|
||
|
|
.
|
||
|
|
.SH "ENVIRONMENT"
|
||
|
|
.
|
||
|
|
.TP
|
||
|
|
\fBBUNYAN_NO_COLOR\fR
|
||
|
|
Set to a non\-empty value to force no output coloring\. See \'\-\-no\-color\'\.
|
||
|
|
.
|
||
|
|
.SH "PROJECT & BUGS"
|
||
|
|
\fBbunyan\fR is written in JavaScript and requires node\.js (\fBnode\fR)\. The project lives at \fIhttps://github\.com/trentm/node\-bunyan\fR and is published to npm as "bunyan"\.
|
||
|
|
.
|
||
|
|
.IP "\(bu" 4
|
||
|
|
README, Install notes: \fIhttps://github\.com/trentm/node\-bunyan#readme\fR
|
||
|
|
.
|
||
|
|
.IP "\(bu" 4
|
||
|
|
Report bugs to \fIhttps://github\.com/trentm/node\-bunyan/issues\fR\.
|
||
|
|
.
|
||
|
|
.IP "\(bu" 4
|
||
|
|
See the full changelog at: \fIhttps://github\.com/trentm/node\-bunyan/blob/master/CHANGES\.md\fR
|
||
|
|
.
|
||
|
|
.IP "" 0
|
||
|
|
.
|
||
|
|
.SH "LICENSE"
|
||
|
|
MIT License (see \fIhttps://github\.com/trentm/node\-bunyan/blob/master/LICENSE\.txt\fR)
|
||
|
|
.
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
node\-bunyan is Copyright (c) 2012 Joyent, Inc\. Copyright (c) 2012 Trent Mick\. All rights reserved\.
|