Name: js-handler/node_modules/restify/node_modules/bunyan/docs/bunyan.1.ronn 
1:
# bunyan(1) -- filter and pretty-print Bunyan log file content
2:
 
3:
 
4:
## SYNOPSIS
5:
 
6:
`bunyan` \[OPTIONS\]
7:
 
8:
... | `bunyan` \[OPTIONS\]
9:
 
10:
`bunyan` \[OPTIONS\] -p PID
11:
 
12:
 
13:
## DESCRIPTION
14:
 
15:
"Bunyan" is **a simple and fast a JSON logging library** for node.js services,
16:
a one-JSON-object-per-line log format, and **a `bunyan` CLI tool** for nicely
17:
viewing those logs. This man page describes the latter.
18:
 
19:
 
20:
### Pretty-printing
21:
 
22:
A bunyan log file is a stream of JSON objects, optionally interspersed with
23:
non-JSON log lines. The primary usage of bunyan(1) is to pretty print,
24:
for example:
25:
 
26:
    $ bunyan foo.log          # or `cat foo.log | bunyan
27:
    [2012-02-08T22:56:52.856Z]  INFO: myservice/123 on example.com: My message
28:
        extra: multi
29:
        line
30:
    [2012-02-08T22:56:54.856Z] ERROR: myservice/123 on example.com: My message
31:
    ...
32:
 
33:
By default the "long" output format is used. Use the `-o FORMAT` option to
34:
emit other formats. E.g.:
35:
 
36:
    $ bunyan foo.log -o short
37:
    22:56:52.856Z  INFO myservice: My message
38:
        extra: multi
39:
        line
40:
    22:56:54.856Z ERROR myservice: My message
41:
    ...
42:
 
43:
These will color the output if supported in your terminal.
44:
See "OUTPUT FORMATS" below.
45:
 
46:
 
47:
### Filtering
48:
 
49:
The `bunyan` CLI can also be used to filter a bunyan log. Use `-l LEVEL`
50:
to filter by level:
51:
 
52:
    $ bunyan foo.log -l error       # show only 'error' level records
53:
    [2012-02-08T22:56:54.856Z] ERROR: myservice/123 on example.com: My message
54:
 
55:
Use `-c COND` to filter on a JavaScript expression returning true on the
56:
record data. In the COND code, `this` refers to the record object:
57:
 
58:
    $ bunyan foo.log -c `this.three`     # show records with the 'extra' field
59:
    [2012-02-08T22:56:52.856Z]  INFO: myservice/123 on example.com: My message
60:
        extra: multi
61:
        line
62:
 
63:
 
64:
## OPTIONS
65:
 
66:
  * `-h`, `--help`:
67:
    Print this help info and exit.
68:
 
69:
  * `--version`:
70:
    Print version of this command and exit.
71:
 
72:
  * `-q`, `--quiet`:
73:
    Don't warn if input isn't valid JSON.
74:
 
75:
Dtrace options (only on dtrace-supporting platforms):
76:
 
77:
  * `-p PID`, `-p NAME`:
78:
    Process bunyan:log-\* probes from the process with the given PID.
79:
    Can be used multiple times, or specify all processes with '\*',
80:
    or a set of processes whose command & args match a pattern with
81:
    '-p NAME'.
82:
 
83:
Filtering options:
84:
 
85:
  * `-l`, `--level LEVEL`:
86:
    Only show messages at or above the specified level. You can specify level
87:
    *names* or numeric values. (See 'Log Levels' below.)
88:
 
89:
  * `-c COND`, `--condition COND`:
90:
    Run each log message through the condition and only show those that
91:
    resolve to a truish value. E.g. `-c 'this.pid == 123'`.
92:
 
93:
  * `--strict`:
94:
    Suppress all but legal Bunyan JSON log lines. By default non-JSON, and
95:
    non-Bunyan lines are passed through.
96:
 
97:
Output options:
98:
 
99:
  * `--color`:
100:
    Colorize output. Defaults to try if output stream is a TTY.
101:
 
102:
  * `--no-color`:
103:
    Force no coloring (e.g. terminal doesn't support it)
104:
 
105:
  * `-o FORMAT`, `--output FORMAT`:
106:
    Specify an output format. One of `long` (the default), `short`, `json`,
107:
    `json-N`, `bunyan` (the native bunyan 0-indent JSON output) or `inspect`.
108:
 
109:
  * `-j`:
110:
    Shortcut for `-o json`.
111:
 
112:
 
113:
## LOG LEVELS
114:
 
115:
In Bunyan log records, then `level` field is a number. For the `-l|--level`
116:
argument the level **names** are supported as shortcuts. In `-c|--condition`
117:
scripts, uppercase symbols like "DEBUG" are defined for convenience.
118:
 
119:
    Level Name      Level Number    Symbol in COND Scripts
120:
    trace           10              TRACE
121:
    debug           20              DEBUG
122:
    info            30              INFO
123:
    warn            40              WARN
124:
    error           50              ERROR
125:
    fatal           60              FATAL
126:
 
127:
 
128:
## OUTPUT FORMATS
129:
 
130:
    FORMAT NAME         DESCRIPTION
131:
    long (default)      The default output. Long form. Colored and "pretty".
132:
                        'req' and 'res' and 'err' fields are rendered specially
133:
                        as an HTTP request, HTTP response and exception
134:
                        stack trace, respectively. For backward compat, the
135:
                        name "paul" also works for this.
136:
    short               Like the default output, but more concise. Some
137:
                        typically redundant fields are ellided.
138:
    json                JSON output, 2-space indentation.
139:
    json-N              JSON output, N-space indentation, e.g. "json-4"
140:
    bunyan              Alias for "json-0", the Bunyan "native" format.
141:
    inspect             Node.js `util.inspect` output.
142:
 
143:
 
144:
## DTRACE SUPPORT
145:
 
146:
On systems that support DTrace (e.g., MacOS, FreeBSD, illumos derivatives
147:
like SmartOS and OmniOS), Bunyan will create a DTrace provider (`bunyan`)
148:
that makes available the following probes:
149:
 
150:
    log-trace
151:
    log-debug
152:
    log-info
153:
    log-warn
154:
    log-error
155:
    log-fatal
156:
 
157:
Each of these probes has a single argument: the string that would be
158:
written to the log.  Note that when a probe is enabled, it will
159:
fire whenever the corresponding function is called, even if the level of
160:
the log message is less than that of any stream.
161:
 
162:
See <https://github.com/trentm/node-bunyan#dtrace-support> for more details
163:
and the '-p PID' option above for convenience usage.
164:
 
165:
 
166:
## ENVIRONMENT
167:
 
168:
  * `BUNYAN_NO_COLOR`:
169:
    Set to a non-empty value to force no output coloring. See '--no-color'.
170:
 
171:
 
172:
## PROJECT & BUGS
173:
 
174:
`bunyan` is written in JavaScript and requires node.js (`node`). The project
175:
lives at <https://github.com/trentm/node-bunyan> and is published to npm as
176:
"bunyan".
177:
 
178:
* README, Install notes: <https://github.com/trentm/node-bunyan#readme>
179:
* Report bugs to <https://github.com/trentm/node-bunyan/issues>.
180:
* See the full changelog at: <https://github.com/trentm/node-bunyan/blob/master/CHANGES.md>
181:
 
182:
 
183:
## LICENSE
184:
 
185:
MIT License (see <https://github.com/trentm/node-bunyan/blob/master/LICENSE.txt>)
186:
 
187:
 
188:
## COPYRIGHT
189:
 
190:
node-bunyan is Copyright (c) 2012 Joyent, Inc. Copyright (c) 2012 Trent Mick.
191:
All rights reserved.