node-bunyan-lite/docs/bunyan.1

232 lines
6.4 KiB
Groff
Raw Permalink Normal View History

2012-10-25 18:15:12 +00:00
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
2014-08-25 06:44:57 +00:00
.TH "BUNYAN" "1" "August 2014" "" "bunyan manual"
2012-10-25 18:15:12 +00:00
.
.SH "NAME"
\fBbunyan\fR \- filter and pretty\-print Bunyan log file content
.
.SH "SYNOPSIS"
2012-11-13 08:12:57 +00:00
\fBbunyan\fR [OPTIONS]
.
.P
\&\.\.\. | \fBbunyan\fR [OPTIONS]
.
.P
\fBbunyan\fR [OPTIONS] \-p PID
2012-10-25 18:15:12 +00:00
.
.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
2012-11-02 06:49:09 +00:00
Dtrace options (only on dtrace\-supporting platforms):
.
.TP
2012-11-13 08:12:57 +00:00
\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\'\.
2012-11-02 06:49:09 +00:00
.
.P
2012-10-25 18:15:12 +00:00
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
2014-08-25 06:44:57 +00:00
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\.
2012-10-25 18:15:12 +00:00
.
.TP
\fB\-j\fR
Shortcut for \fB\-o json\fR\.
.
.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
2014-08-25 06:44:57 +00:00
long (default) The default output\. Long form\. Colored and "pretty"\.
2012-10-25 18:15:12 +00:00
\'req\' and \'res\' and \'err\' fields are rendered specially
as an HTTP request, HTTP response and exception
2014-08-25 06:44:57 +00:00
stack trace, respectively\. For backward compat, the
name "paul" also works for this\.
2012-10-25 18:15:12 +00:00
short Like the default output, but more concise\. Some
typically redundant fields are ellided\.
json JSON output, 2\-space indentation\.
2014-08-25 06:44:57 +00:00
json\-N JSON output, N\-space indentation, e\.g\. "json\-4"
bunyan Alias for "json\-0", the Bunyan "native" format\.
2012-10-25 18:15:12 +00:00
inspect Node\.js `util\.inspect` output\.
.
.fi
.
2012-11-02 06:49:09 +00:00
.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
2012-11-13 08:12:57 +00:00
See \fIhttps://github\.com/trentm/node\-bunyan#dtrace\-support\fR for more details and the \'\-p PID\' option above for convenience usage\.
2012-11-02 06:49:09 +00:00
.
.SH "ENVIRONMENT"
.
.TP
\fBBUNYAN_NO_COLOR\fR
Set to a non\-empty value to force no output coloring\. See \'\-\-no\-color\'\.
.
2012-10-25 18:15:12 +00:00
.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\.