Recover from npm package

[rbdr/cologne] / README.md

diff --git a/README.md b/README.md
index 87f808f339fdd48df5b6c081c7367c0e6044f4f3..bf2ae2d15be8c7aa18a5ae3e7e7e161119d2635b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,263 +1,300 @@
-# Cobalt #
+# Cologne

 
 

-Cobalt is a simple logger multiplexer that works with a JSON based format.
-You can instantiate it with a set of loggers or add them later
-(see API reference below). When logging anything, Cobalt will attempt to
-generate an Object that conforms to the Cobalt Log Format Definition
-(if required) and passes it to every logger it has by calling their `log`
-method.
+![https://david-dm.org/rbdr/cologne.svg][dependencies-shield]
+![https://circleci.com/gh/rbdr/cologne.svg?style=shield][circle-ci-shield]

 
 

-Example of instantiating a cobalt logger:
+Cologne is a logger multiplexer that works mainly with a JSON format. It
+can be instantiated with several loggers, or they can be changed after
+the fact.
+
+## Usage
+
+Install from npm or add to your package.json:

 
 

-In node:

 ```
 ```

-require('cobalt-log');
+$ npm install cologne

 ```
 
 ```
 

-In the browser just require the files. Then:
+Create an instance:

 
 

-```
-this.logger = new Cobalt.Console({
-  from : "Breezi Client",
-  loggers : [ new Cobalt.Logger.JsConsole({
-              formatter : Cobalt.Formatter.Token,
-              formatterOpts : {
-                formatString : "{{_from}}: {{message}}",
-                ansiColor : true
-              }
-            })]
+```javascript
+require('cologne');
+
+let co = new Cologne({
+  from: "Special Worker Logger",
+  loggers: [
+    new Cologne.Logger.Console({
+      formatter: new Cologne.Formatter.Token({
+        formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
+      })
+    })
+  ]

 });
 ```
 
 });
 ```
 

-This code will create an instance with a JsConsole logger that uses the
-Token formatter (See loggers and formatters below).
+This example would create a cologne instance with a console logger that
+uses a Token formatter. (More on loggers and formatters below.);

 
 

-Cobalt works in a browser or inside node, so feel free to use cobalt all
-over! (Also, see the socket logger below for info on connecting cobalt
-loggers)
+## Do I need anything special?

 
 

-## Quick API Reference ##
+Node 4.0+

 
 

-* **addLogger(logger)**: Adds a logger to the cobalt instance.
-* **removeLogger(logger)**: Removes a logger from the cobalt instance.
-* **buildLog(item, level=7)**: Generates a cobalt log object as if you had
-  logged item (it will do this automatically when you log anything)
-* **extendLog(object)**: Creates a dummy log object and extends it with
-  object.
-* **buildSeparator**: Generates a cobalt log object that defines a separator
+## Quick API Reference
+
+* **addLogger(logger)**: Adds a logger to the cologne instance.
+* **removeLogger(logger)**: Removes a logger from the cologne instance.
+* **buildLog(item, level, [meta])**: Generates a cologne log object as if you had
+  logged an item (it will do this automatically when you log anything.)
+  level defaults to 6. You can optionally send it an object to extend
+  the object with.

 * **log, info, notice, warn, error**: Generates a log object with the
   appropriate severity level and sends it to all loggers.
 * **log, info, notice, warn, error**: Generates a log object with the
   appropriate severity level and sends it to all loggers.

-* **separator()**: Generates a separator log object and sends it to all
-  loggers.
-* **space(lines)**: Logs an empty string `lines` times
-* **indent()**: Increases the indent level globally.
-* **indent(callback)**: Increases the indent level for anything logged
-  from inside the callback.
-* **outdent()/outdent(callback)**: Same as indent, but decreases indent level.
-* **color()**: Changes the color globally. †
-* **color(callback)**: Changes the color for anything logged from inside the
-  callback. †
-* **now()**: Returns the current time in microseconds, using performance.now()
-  or process.hrtime() if available. If not, falls back to miliseconds.
-
-† Cobalt doesn't really care about formatting or colors, but it allows you
-to set the `_color` property in the generated object. In the end, it's up to
-the formatter to decide if it will use this property. However, this maintains
-the old cobalt API and gives you flexibility in how you color your logs.
-
-
-## Loggers ##
-
-Cobalt doesn't depend on any particular logger, and the loggers it expects
-to receive is any object that responds to the log method. However, since it
-would pass a JSON object instead of a string, this may result in unexpected
-behavior for loggers that don't expect it. To ease the use of Cobalt with
-existing loggers, cobalt includes a couple of loggers that you can use out
-of the box.
-
-
-### Cobalt.Logger.JsConsole ###
-
-This logger communicates the Javascript console present in web browsers or
-node with cobalt. It uses the logLevel to trigger the appropriate method
-(e.g. info vs warn vs error). You can also initialize it with a formatter,
-to convert the log object to a string:

 
 

-```
- new Cobalt.Logger.JsConsole({
-     formatter : Cobalt.Formatter.Token,
-     formatterOpts : {
-         formatString : "[{{_timestamp}}] {{message}} (@{{_from}})"
-     }
- }) 
-```
+## Loggers

 
 

-What this does is: it will trigger the method `format` on `formatter`
-passing the `logObject` and `formatterOpts`. This means that a formatter is
-any object that responds to `format(logObject, formatterOpts)`. It expects
-a string to be returned.
+Cologne loggers are any object that responds to the `#log()` method.
+This methoud should be able to receive any number of arguments and
+log them independently. Similar to how you can send multiple arguments
+to the JS console.

 
 

-### Cobalt.Logger.File ###
+`#log()` will receive any number of `Cologne Log Objects`. To see what
+this format includes, check further below.

 
 

-This logger communicates a file via a writable stream, and is intended
-only for node. Like the JSConsole logger, you can also initialize it with
-a formatter to convert the log object to a string:
+We include two loggers out of the box:

 
 

+* `Cologne.Logger.Console` logs to the JS console
+* `Cologne.Logger.File` appends to a file
+
+### Cologne.Logger.Console
+
+This logger communicates the Javascript console. It uses the log level
+to trigger the appropriate method, so `error` logs would go to stderr
+as expected when calling `console.error`.
+
+This logger can be sent a `formatter`, which is an object that responds
+to the `#format()` method: it should get a cologne log object and respond
+with a string.
+
+```javascript
+new Cologne.Logger.Console({
+  formatter : new Cologne.Formatter.Token({
+    formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
+  })
+});

 ```
 ```

- new Cobalt.Logger.File({
-     formatter : Cobalt.Formatter.Token,
-     formatterOpts : {
-         formatString : "[{{_timestamp}}] {{message}} (@{{_from}})"
-     }
- }) 
-```

 
 

-What this does is: it will trigger the method `format` on `formatter`
-passing the `logObject` and `formatterOpts`. This means that a formatter is
-any object that responds to `format(logObject, formatterOpts)`. It expects
-a string to be returned.
+### Cologne.Logger.File
+
+This logger opens a writable stream to a file, to which it will append
+everything. Like the Console logger it supports a `formatter` property
+that will respond to the `#format()` method.
+
+It MUST include a `file` property on initialization, otherwise it won't
+know where to write and you'll get an exception and be sad.
+
+```javascript
+new Cologne.Logger.File({
+  file: '/var/log/server_log.log',
+  formatter : new Cologne.Formatter.Token({
+    formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
+  })
+});
+```

 
 

-### Cobalt.Logger.Socket ###
+### More Loggers?

 
 

-This logger sends the log object to a socket using Socket.IO. It does not
-format the output. To catch the log from the recipient, you have to listen
-for the `log` event, and from there you can pass it to another Cobalt
-instance or do whatever you want with it.
+We're working on a socket logger. It's separate so you don't have to
+install the socket dependencies if you don't want to.

 
 

-### More Loggers? ###
+If you need to, you can roll your own. Check info on the interfaces
+below.

 
 You can build your own logger easily for any method of transport you find
 necessary (e.g. mail, database, twitter, etc). Any object that responds
 
 You can build your own logger easily for any method of transport you find
 necessary (e.g. mail, database, twitter, etc). Any object that responds

-to `#log(logObject)` is a valid logger:
+to `#log()` is a valid logger:

 
 ```javascript
 // A valid, very minimalistic logger
 
 ```javascript
 // A valid, very minimalistic logger

-var simpleLogger = {
-  log : function (logObject) {
-    console.log(logObject.message);
+let simpleLogger = {
+  log : function () {
+    for (let logObject of arguments) {
+      this._doSomeMagic(logObject);
+    }
+  },
+
+  _doSomeMagic : function (logObject) {
+    console.log(logObject + "... but magical!");

   }
   }

-}
+};

 
 logger.addLogger(simpleLogger);
 ```
 
 
 logger.addLogger(simpleLogger);
 ```
 

-## Formatters ##

 
 

-Cobalt itself makes no assumptions about the output of the logger and just
-passes the object to every logger it has. However, it is clear that loggers
-may want to manipulate this object. As shown in the JsConsole, a formatter
-should respond to the format method and receive a `logObject` and an
-`optsObject`. However, as this is not a core part of Cobalt, this is only a
-recommendation (as this is the way the included JsConsole/File loggers do it)
-and it is up to the logger on how to transform the object it receives.
+## Formatters
+
+Cologne doesn't need formatters to work, and in fact they're optional in
+the included workers. But if you would like to make your logs prettier,
+then you can use one of the included formatters or roll your own.
+
+Formatters are objects that respond to the `#format()` method. It will
+receive a single cologne log object (see fields it includes below), and
+it should return a string. That's all there is to it.

 
 

-### Cobalt.Formatter.Simple ###
+We include some formatters so you can get running real quicklike:
+
+* `Cologne.Formatter.Simple` a simple predefined formatter
+* `Cologne.Formatter.Token` a formatter that lets you define format
+  strings that it will use to build your final log.
+
+### Cologne.Formatter.Simple

 
 This is the lazy formatter, it just outputs the string in the following
 format:
 
 ```
 
 This is the lazy formatter, it just outputs the string in the following
 format:
 
 ```

-'[{{_timestamp}}][{{_logLevelString}}]{{_from}}: {{_message}}'
+'[{{_timestamp}}][{{_levelString}}]{{_from}}: {{message}}'

 ```
 
 Where `_timestamp` is converted to ISO.
 
 ```
 
 Where `_timestamp` is converted to ISO.
 

-Example output:
+#### Accepted Options
+
+* `colorize` <Boolean>: whether or not to add color. False by default.
+
+By default we don't colorize the output, but if you enable the flag this
+formatter will add a bit of color in the level string. Red for bad,
+yellow for warn, blue for info, and white for everything else.

 
 

+#### Usage
+
+```javascript
+new Cologne.Formatter.Simple({
+  colorize: true
+});

 ```
 ```

-cobalt.log("hello world");
-// -> [2015-01-09T16:02:23.102Z][INFO] Generic Cobalt Logger : hello world
+
+### Example Output
+
+```
+co.log("hello world");
+// -> [2016-01-21T05:50:36.505Z][INFO] Server Logger: hello world

 ```
 
 ```
 

-### Cobalt.Formatter.Token ###
+### Cologne.Formatter.Token

 
 

-The Token formatter is a more advanced, but still fairly simple
-formatter. It takes a `formatString` and interpolates the properties
-of the object. By default it transforms anything inside double curly
-braces `{{likeThis}}`, however you can set a custom `replaceRule`.
+The token formatter lets you build strings with simple tokens. When
+instantiating, you can specify a `formatString` to interpolate
+properties from the logObject. The default version looks for tokens
+inside double curly braces like `{{message}}` or `{{_level}}`. If
+you don't like it, you can specify your own.

 
 

-#### Accepted Options ####
+#### Accepted Options

 
 

-* `formatString` : The string used to replace. Defaults to `"{{message}}"`
-* `replaceRule` : The regex rule to use for replacement of tokens in the
+* `formatString` <String>: The string used to replace. Defaults to `"{{message}}"`
+* `replaceRule` <String>: The regex rule to use for replacement of tokens in the

   formatString. Defaults to `/{{(.*?)}}/g`
   formatString. Defaults to `/{{(.*?)}}/g`

-* `separatorLength` <Number> : How long to print separators. Defaults to 60.

 * `isoDate` <Boolean> : Whether or not to convert `_timestamp` to ISO
 * `isoDate` <Boolean> : Whether or not to convert `_timestamp` to ISO

-  date. Defaults to true.
-* `separatorType` <String> : The string to use for the separator.
-  Defaults to `"="`
-* `ansiColor` <Boolean> : Whether to use ANSI colors for output.
-  Defaults to `false`. This options depends on `colors`
-
-#### Options ####
-
-* **formatString**: A string that defines the format of the output. It is a
-  string with double curly braces denoting fields. For example:
-  `"[{{_timestamp}}] {{message}} (@{{_from}})"` would attempt to extract the
-  \_timestamp, message and \_from fields to create a string similar to this:
-  `"[124896126491.123] Testing the logger (@Client Application)"`
-  (defaults to `"{{message}}"`)
-* **ansiColor**: A boolean value, when `true` will output the string in ANSI
-  color depending on the severity level (defaults to `false`)
-
-### More Formatters? ###
-
-As with loggers, cobalt itself does not worry about these things. However,
-if you wish to make a formatter that is exchangable with Token, you just
-need to create an object that responds to the`format(logObject, optionsObject)`
-method:
+  date. Defaults to true. Otherwise it'll use the raw timestamp.
+
+#### Usage
+
+```javascript
+new Cologne.Formatter.Token({
+  formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
+});
+```
+
+#### ANSI tokens
+
+If you want to add color to your logs, you can use the special \_ansi
+token. It has several options which you can call like `{{_ansi:red}}`
+and `{{_ansi:reset}}`. Here's a list of all the ansi stuff you can use:
+
+* `bold`: makes text bold
+* `italics`: makes text italics
+* `underline`: makes text underlined
+* `inverse`: inverts foreground and background
+* `strikethrough`: strikethrough text
+* `bold_off`, `italics_off`, `underline_off`, `inverse_off`, and
+  `strikethrough_off`: turn off the specified effect.
+* `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`,
+  and `default`: change the foreground color of your text.
+* `black_bg`, `red_bg`, `green_bg`, `yellow_bg`, `blue_bg`, `magenta_bg`,
+  `cyan_bg`, `white_bg`, and `default_bg`: change the background color of your
+  text.
+* `reset`: makes everything normal again.
+* `_level`: this is a special code that will set a color depending on
+  the level of the log: debug gets green, info and notice blue, warn is
+  yellow, and anything worse is red.
+
+### More Formatters?
+
+You can create your own formatters by creating an object that responds
+to the `#format()` method, knows how to handle cologne log objects and
+returns a string.
+
+Here's an example of a logger that surrounds a log with sparkles:

 
 ```javascript
 
 ```javascript

-// A valid, very minimalistic formatter

 var simpleFormatter = {
 var simpleFormatter = {

-  format : function (logObject, options) {
-    if (options.showDate) {
-      return "[" + Date(logObject._timeStamp) + "] " + logObject.message
-    } else {
-      return logObject.message;
-    }
+  format : function (logObject) {
+    return '✨' + logObject.message + '✨';

   }
 }
 
   }
 }
 

-logger.addLogger(new Cobalt.Logger.JsConsole({
-  formatter: simpleFormatter,
-  formatterOpts : {
-    showDate : true
-  }
+logger.addLogger(new Cologne.Logger.Console({
+  formatter: simpleFormatter

 }));
 ```
 
 }));
 ```
 

-## The Cobalt Log Format ##
+## The Cologne Log Format
+
+The cologne log format is a JSON based log format, based on the cobalt
+log format, which is inturn based on Graylog's GELF. However, where GELF
+treats all internal fields without a prefix, and all user fields with a
+prefix we do it backwards so it's easier to extend the object with
+metadata from existing objects. Besides, we'll probably write the
+default keys automatically so you shouldn't have to do that extra work.

 
 

-The Cobalt Log (CoLog) format is a JSON based log format used with cobalt.
-It is partly inspired in Greylog's GELF format, but with very notorious
-differences. The CoLog requires a header with certain fields that allow
-cobalt and its pieces to handle it. All header fields are prefixed with
-an underscore. Other than those fields, you can put whatever you want in
-the object; It's up to the loggers to make sense of the structure and
-display it in a way that makes sense.
+You could try to build it on your own, but you can use `#buildLog()`
+to build it without logging.

 
 

-You can attempt to build this structure on your own, or let cobalt build it for 
-you. Any object you pass for logging will be converted. However, if you
-build it on your own you have two options: The first one is use buildLog
-to create a log object for "item" as if you had logged "item" or you can
-use extendLog that will create a dummy log object and extends it with
-whatever object you pass to it.
+### Fields

 
 

-### Required Fields ###
+* **\_timestamp** : A timestamp in miliseconds with fractions of a second
+  in the floating point area.
+* **\_cologneLog** <String> : This is how we know if the log is already
+  formatted and ready to go. This field is a string containing the
+  version of cologne log format it's using. It's `1.0.0` right now.
+* **\_from**: The sender of the log (Defaults to Generic Cologne Logger)
+* **\_level**: The level of the log (Defaults to 6)
+* **\_levelString**: The string corresponding to the log level (e.g. 7 ->
+  debug, 3 -> error, 0 -> emerg)

 
 

-* **_version** : The version of cobalt this is designed to work with
-* **_timestamp** : A timestamp in microseconds.
-* **_cobaltLog** [true] : Cobalt will check for the \_cobaltLog to decide if
-transformation will happen or not.
+### A word on Log Levels

 
 

-### Optional Fields ###
+The log levels in cologne correspond to the syslog levels, and the
+levelStrings correspond to the priority keywords:

 
 

-* **\_from**: The sender of the log (Defaults to Generic Cobalt Logger)
-* **\_level**: The level of the log (Defaults to 7)
-* **\_levelString**: The string corresponding to the log level (e.g. 7 ->
-  DEBUG, 3 -> ERROR, 0 -> CRIT)
-* **\_indentLevel**: The indent level of the log
-* **\_color**: The color of the log
-* **\_separator**: If true, indicates that this is a separator and holds no
-  valuable information.
+* `0 -> emerg`
+* `1 -> alert`
+* `2 -> crit`
+* `3 -> error`
+* `4 -> warning`
+* `5 -> notice`
+* `6 -> info`
+* `7 -> debug`
+
+This is useful when deciding how to log. You could even have a logger
+filter out unnecessary levels (eg. If you have a reporting logger that
+only reports error or worse.)
+
+## Further Improvements
+
+* Improve the API for buildLog
+* More loggers & formatters (will not be distributed in core cologne)
+* Improve tests
+
+[dependencies-shield]: https://david-dm.org/rbdr/cologne.svg
+[circle-ci-shield]: https://circleci.com/gh/rbdr/cologne.svg?style=shield