From 432eec6f2908d7a1c361b05f0f28b16ed5c1c948 Mon Sep 17 00:00:00 2001 From: Trent Mick Date: Thu, 25 Oct 2012 11:15:12 -0700 Subject: [PATCH] add a man page --- CHANGES.md | 2 +- LICENSE.txt | 23 +++++ Makefile | 19 ++++ docs/bunyan.1 | 187 ++++++++++++++++++++++++++++++++++++ docs/bunyan.1.html | 233 +++++++++++++++++++++++++++++++++++++++++++++ docs/bunyan.1.ronn | 150 +++++++++++++++++++++++++++++ docs/index.html | 1 + 7 files changed, 614 insertions(+), 1 deletion(-) create mode 100644 LICENSE.txt create mode 100644 docs/bunyan.1 create mode 100644 docs/bunyan.1.html create mode 100644 docs/bunyan.1.ronn create mode 100644 docs/index.html diff --git a/CHANGES.md b/CHANGES.md index 708841b..e9b59a1 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,7 +2,7 @@ ## bunyan 0.14.7 (not yet released) -(nothing yet) +- Add a man page. See . ## bunyan 0.14.6 diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..964efc1 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,23 @@ +# This is the MIT license + +Copyright (c) 2011-2012 Joyent Inc. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + diff --git a/Makefile b/Makefile index 42efc41..502455c 100644 --- a/Makefile +++ b/Makefile @@ -27,6 +27,25 @@ cutarelease: versioncheck [[ `git status | tail -n1` == "nothing to commit (working directory clean)" ]] ./tools/cutarelease.py -p bunyan -f package.json -f lib/bunyan.js -f bin/bunyan +.PHONY: docs +docs: + @[[ `which ronn` ]] || (echo "No 'ronn' on your PATH. Install with 'gem install ronn'" && exit 2) + mkdir -p man/man1 + ronn --style=toc --manual="bunyan manual" --date=$(shell git log -1 --pretty=format:%cd --date=short) --roff --html docs/bunyan.1.ronn + python -c 'import sys; h = open("docs/bunyan.1.html").read(); h = h.replace(".mp dt.flush {float:left;width:8ex}", ""); open("docs/bunyan.1.html", "w").write(h)' + python -c 'import sys; h = open("docs/bunyan.1.html").read(); h = h.replace("", """Fork me on GitHub"""); open("docs/bunyan.1.html", "w").write(h)' + @echo "# test with 'man ./docs/bunyan.1' and 'open ./docs/bunyan.1.html'" + +.PHONY: publish +publish: + mkdir -p tmp + [[ -d tmp/bunyan-gh-pages ]] || git clone git@github.com:trentm/node-bunyan.git tmp/bunyan-gh-pages + cd tmp/bunyan-gh-pages && git checkout gh-pages && git pull --rebase origin gh-pages + cp docs/index.html tmp/bunyan-gh-pages/index.html + cp docs/bunyan.1.html tmp/bunyan-gh-pages/bunyan.1.html + (cd tmp/bunyan-gh-pages \ + && git commit -a -m "publish latest docs" \ + && git push origin gh-pages || true) #---- test diff --git a/docs/bunyan.1 b/docs/bunyan.1 new file mode 100644 index 0000000..47c4040 --- /dev/null +++ b/docs/bunyan.1 @@ -0,0 +1,187 @@ +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "BUNYAN" "1" "October 2012" "" "bunyan manual" +. +.SH "NAME" +\fBbunyan\fR \- filter and pretty\-print Bunyan log file content +. +.SH "SYNOPSIS" +\fBbunyan\fR [OPTIONS] [LOOKUPS\.\.\.] +. +.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 +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 \fBpaul\fR (the default), \fBshort\fR, \fBjson\fR, \fBjson\-N\fR, or \fBinspect\fR\. +. +.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 +paul (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\. Note: the "paul" name + is deprecated and will be changed to "long"\. +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\-0" +inspect Node\.js `util\.inspect` output\. +. +.fi +. +.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\. diff --git a/docs/bunyan.1.html b/docs/bunyan.1.html new file mode 100644 index 0000000..2623bbd --- /dev/null +++ b/docs/bunyan.1.html @@ -0,0 +1,233 @@ + + + + + + bunyan(1) - filter and pretty-print Bunyan log file content + + + + + +
+ + + +
    +
  1. bunyan(1)
    2. +
  2. bunyan manual
    3. +
  3. bunyan(1)
    4. +
+ +

NAME

+

+ bunyan - filter and pretty-print Bunyan log file content +

+ +

SYNOPSIS

+ +

bunyan [OPTIONS] [LOOKUPS...]

+ +

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.

+
+ + +

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 paul (the default), short, json, +json-N, or inspect.

+
-j

Shortcut for -o json.

+
+ + +

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
+paul (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. Note: the "paul" name
+                    is deprecated and will be changed to "long".
+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-0"
+inspect             Node.js `util.inspect` output.
+
+ +

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".

+ + + + +

LICENSE

+ +

MIT License (see https://github.com/trentm/node-bunyan/blob/master/LICENSE.txt)

+ + + +

node-bunyan is Copyright (c) 2012 Joyent, Inc. Copyright (c) 2012 Trent Mick. +All rights reserved.

+ + +
    +
  1. +
  2. October 2012
    3. +
  3. bunyan(1)
    4. +
+ +
+Fork me on GitHub + diff --git a/docs/bunyan.1.ronn b/docs/bunyan.1.ronn new file mode 100644 index 0000000..ec72989 --- /dev/null +++ b/docs/bunyan.1.ronn @@ -0,0 +1,150 @@ +# bunyan(1) -- filter and pretty-print Bunyan log file content + + +## SYNOPSIS + +`bunyan` \[OPTIONS\] \[LOOKUPS...\] + + +## 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. + +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 `paul` (the default), `short`, `json`, + `json-N`, or `inspect`. + + * `-j`: + Shortcut for `-o json`. + + +## 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 + paul (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. Note: the "paul" name + is deprecated and will be changed to "long". + 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-0" + inspect Node.js `util.inspect` output. + + +## PROJECT & BUGS + +`bunyan` is written in JavaScript and requires node.js (`node`). The project +lives at and is published to npm as +"bunyan". + +* README, Install notes: +* Report bugs to . +* See the full changelog at: + + +## LICENSE + +MIT License (see ) + + +## COPYRIGHT + +node-bunyan is Copyright (c) 2012 Joyent, Inc. Copyright (c) 2012 Trent Mick. +All rights reserved. diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..4defe1a --- /dev/null +++ b/docs/index.html @@ -0,0 +1 @@ +bunyan(1) man page