196 lines
5.9 KiB
Markdown
196 lines
5.9 KiB
Markdown
# bunyan(1) -- filter and pretty-print Bunyan log file content
|
|
|
|
|
|
## SYNOPSIS
|
|
|
|
`bunyan` \[OPTIONS\]
|
|
|
|
... | `bunyan` \[OPTIONS\]
|
|
|
|
`bunyan` \[OPTIONS\] -p PID
|
|
|
|
|
|
## DESCRIPTION
|
|
|
|
"Bunyan" is **a simple and fast a JSON logging library** for node.js services,
|
|
a one-JSON-object-per-line log format, and **a `bunyan` CLI tool** for nicely
|
|
viewing those logs. This man page describes the latter.
|
|
|
|
|
|
### 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:
|
|
|
|
$ 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
|
|
...
|
|
|
|
By default the "long" output format is used. Use the `-o FORMAT` option to
|
|
emit other formats. E.g.:
|
|
|
|
$ bunyan foo.log -o short
|
|
22:56:52.856Z INFO myservice: My message
|
|
extra: multi
|
|
line
|
|
22:56:54.856Z ERROR myservice: My message
|
|
...
|
|
|
|
These will color the output if supported in your terminal.
|
|
See "OUTPUT FORMATS" below.
|
|
|
|
|
|
### Filtering
|
|
|
|
The `bunyan` CLI can also be used to filter a bunyan log. Use `-l LEVEL`
|
|
to filter by level:
|
|
|
|
$ bunyan foo.log -l error # show only 'error' level records
|
|
[2012-02-08T22:56:54.856Z] ERROR: myservice/123 on example.com: My message
|
|
|
|
Use `-c COND` to filter on a JavaScript expression returning true on the
|
|
record data. In the COND code, `this` refers to the record object:
|
|
|
|
$ 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
|
|
|
|
|
|
## OPTIONS
|
|
|
|
* `-h`, `--help`:
|
|
Print this help info and exit.
|
|
|
|
* `--version`:
|
|
Print version of this command and exit.
|
|
|
|
* `-q`, `--quiet`:
|
|
Don't warn if input isn't valid JSON.
|
|
|
|
Dtrace options (only on dtrace-supporting platforms):
|
|
|
|
* `-p PID`, `-p NAME`:
|
|
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'.
|
|
|
|
Filtering options:
|
|
|
|
* `-l`, `--level LEVEL`:
|
|
Only show messages at or above the specified level. You can specify level
|
|
*names* or numeric values. (See 'Log Levels' below.)
|
|
|
|
* `-c COND`, `--condition COND`:
|
|
Run each log message through the condition and only show those that
|
|
resolve to a truish value. E.g. `-c 'this.pid == 123'`.
|
|
|
|
* `--strict`:
|
|
Suppress all but legal Bunyan JSON log lines. By default non-JSON, and
|
|
non-Bunyan lines are passed through.
|
|
|
|
Output options:
|
|
|
|
* `--color`:
|
|
Colorize output. Defaults to try if output stream is a TTY.
|
|
|
|
* `--no-color`:
|
|
Force no coloring (e.g. terminal doesn't support it)
|
|
|
|
* `-o FORMAT`, `--output FORMAT`:
|
|
Specify an output format. One of `long` (the default), `short`, `json`,
|
|
`json-N`, `bunyan` (the native bunyan 0-indent JSON output) or `inspect`.
|
|
|
|
* `-j`:
|
|
Shortcut for `-o json`.
|
|
|
|
* `-L`, `--time local`:
|
|
Display the time field in *local* time, rather than the default UTC
|
|
time.
|
|
|
|
|
|
## LOG LEVELS
|
|
|
|
In Bunyan log records, then `level` field is a number. For the `-l|--level`
|
|
argument the level **names** are supported as shortcuts. In `-c|--condition`
|
|
scripts, uppercase symbols like "DEBUG" are defined for convenience.
|
|
|
|
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
|
|
|
|
|
|
## OUTPUT FORMATS
|
|
|
|
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.
|
|
|
|
|
|
## DTRACE SUPPORT
|
|
|
|
On systems that support DTrace (e.g., MacOS, FreeBSD, illumos derivatives
|
|
like SmartOS and OmniOS), Bunyan will create a DTrace provider (`bunyan`)
|
|
that makes available the following probes:
|
|
|
|
log-trace
|
|
log-debug
|
|
log-info
|
|
log-warn
|
|
log-error
|
|
log-fatal
|
|
|
|
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.
|
|
|
|
See <https://github.com/trentm/node-bunyan#dtrace-support> for more details
|
|
and the '-p PID' option above for convenience usage.
|
|
|
|
|
|
## ENVIRONMENT
|
|
|
|
* `BUNYAN_NO_COLOR`:
|
|
Set to a non-empty value to force no output coloring. See '--no-color'.
|
|
|
|
|
|
## PROJECT & BUGS
|
|
|
|
`bunyan` is written in JavaScript and requires node.js (`node`). The project
|
|
lives at <https://github.com/trentm/node-bunyan> and is published to npm as
|
|
"bunyan".
|
|
|
|
* README, Install notes: <https://github.com/trentm/node-bunyan#readme>
|
|
* Report bugs to <https://github.com/trentm/node-bunyan/issues>.
|
|
* See the full changelog at: <https://github.com/trentm/node-bunyan/blob/master/CHANGES.md>
|
|
|
|
|
|
## LICENSE
|
|
|
|
MIT License (see <https://github.com/trentm/node-bunyan/blob/master/LICENSE.txt>)
|
|
|
|
|
|
## COPYRIGHT
|
|
|
|
node-bunyan is Copyright (c) 2012 Joyent, Inc. Copyright (c) 2012 Trent Mick.
|
|
All rights reserved.
|