From b3bd83c639ad4fd97559cef52992b7be49bd0d9e Mon Sep 17 00:00:00 2001
From: Trent Mick <trentm@gmail.com>
Date: Mon, 30 Jan 2012 16:30:05 -0800
Subject: [PATCH] some intro docs

---
 README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++------
 TODO.md   |  1 -
 2 files changed, 89 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 2677b4d..83083cc 100644
--- a/README.md
+++ b/README.md
@@ -7,24 +7,97 @@ names for the requisite and common fields for a log record (see below).
 Also: log4j is way more than you need.
 
 
+# Current Status
+
+Just play stuff here. Don't try to use this for realz yet.
+
+
 # Usage
 
-    // hi.js
+The usual. All loggers must provide a "service" name. This is somewhat akin
+to log4j logger "name", but Bunyan doesn't so hierarchical logger names.
+
+    $ cat hi.js
     var Logger = require('bunyan');
-    var log = new Logger({facility: "myapp", level: "info"});
+    var log = new Logger({service: "myapp", level: "info"});
     log.info("hi");
 
-    $ node hi.js
-    {"time":"2012-01-30T00:56:25.842Z","facility":"myapp","level":2,"message":"hi"}
+Log records are JSON. "hostname", "time" and "v" (the Bunyan log
+format version) are added for you.
 
-    $ node hi.js | bunyan  # CLI tool to filter/pretty-print JSON logs.
+    $ node hi.js
+    {"service":"myapp","hostname":"banana.local","level":2,"msg":"hi","time":"2012-01-31T00:07:44.216Z","v":0}
+
+A `bunyan` tool is provided for pretty-printing bunyan logs and, eventually,
+for filtering (e.g. `| bunyan -c 'level>3'`). This shows the default output
+(which is fluid right now) and indented-JSON output. More output formats will
+be added, including support for custom formats.
+
+    $ node hi.js | ./bin/bunyan  # CLI tool to filter/pretty-print JSON logs.
+    [2012-01-31T00:08:11.387Z] INFO: myapp on banana.local: hi (<no-request_id>)
+    
+    $ node hi.js | ./bin/bunyan -o json
     {
-      "time": "2012-01-30T00:56:25.842Z",
-      "facility": "myapp",
+      "service": "myapp",
+      "hostname": "banana.local",
       "level": 2,
-      "message": "hi"
+      "msg": "hi",
+      "time": "2012-01-31T00:10:00.676Z",
+      "v": 0
     }
 
+By default, log output is to stdout. Explicitly that looks like:
+
+    var log = new Logger({service: "myapp", stream: process.stdout});
+
+That is an abbreviated form for a single stream. You can defined multiple
+streams at different levels:
+
+    var log = new Logger({
+      service: "amon",
+      streams: [
+        {
+          level: "info",
+          stream: process.stdout, // log INFO and above to stdout
+        },
+        {
+          level: "error",
+          path: "tmp/error.log"   // log ERROR and above to a file
+        }
+      ]
+    });
+
+Support for syslog is planned.
+
+
+# Future
+
+See "TODO.md", but basically:
+
+- "Renderer" support to handle extracting a JSON object for a log record
+  for particular object types, e.g. an HTTP request. So for example we
+  could do:
+  
+        log.info({req: req}, "something about handling this request")
+
+  And the "req" renderer would extract a reasonable JSON object for that
+  request object -- presumably a subset of all attributes on the request
+  object.
+  
+  This will key off the field name, IOW by convention, rather than getting
+  into `instanceof` grossness.
+
+- Spec'ing and enforcing the fields (from dap's section in eng guide).
+
+- Syslog support. Ring-buffer support for storing last N debug messages
+  (or whatever) in memory to support debugability without too much log load.
+
+- More `bunyan` output formats and filtering features.
+
+- Think about a bunyan dashboard that supports organizing and viewing logs
+  from multiple hosts and services.
+
+
 
 # Levels
 
@@ -34,12 +107,18 @@ Also: log4j is way more than you need.
     info
     debug
 
-TODO
+TODO: doc these.
 
 
 # Log Record Fields
 
-TODO
+TODO: from dap and enforce these
+
+- "request_id" (better name?) can't be required because some things don't
+  happen in a per-request context. Startup and background processing stuff
+  for example. Tho for request-y things, it is strongly encouraged because it
+  allows collating logs from multiple services for the same request.
+
 
 # License
 
diff --git a/TODO.md b/TODO.md
index 58be26d..1a7d181 100644
--- a/TODO.md
+++ b/TODO.md
@@ -5,7 +5,6 @@
     <http://journal.paul.querna.org/articles/2011/12/26/log-for-machines-in-json/>
     require: facility and hostname
 - bunyan cli: more layouts (http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html)
-
 - bunyan cli: filter args a la json
 - bunyan cli: -c COND args a la json
 - docs