Use only ref slug for cache

[rbdr/cologne] / README.md

diff --git a/README.md b/README.md
index bf2ae2d15be8c7aa18a5ae3e7e7e161119d2635b..6772648e0ad49b8981afa2d3fc95b16ec5979251 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,30 +1,27 @@
 # Cologne
 
 # Cologne
 

-![https://david-dm.org/rbdr/cologne.svg][dependencies-shield]
-![https://circleci.com/gh/rbdr/cologne.svg?style=shield][circle-ci-shield]
-
-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
+Cologne is a logger multiplexer that uses a JSON log format inspired in gelf.
+It can be instantiated with several loggers, or they can be changed after

 the fact.
 
 ## Usage
 
 the fact.
 
 ## Usage
 

-Install from npm or add to your package.json:
+Install from npm

 
 ```
 
 ```

-$ npm install cologne
+$ npm install --save cologne

 ```
 
 ```
 

-Create an instance:
+Create an instance

 
 ```javascript
 
 ```javascript

-require('cologne');
+const { Cologne, Loggers, Formatters } = require('cologne');

 
 

-let co = new Cologne({
-  from: "Special Worker Logger",
+const co = new Cologne({
+  from: 'Special Worker Logger',

   loggers: [
   loggers: [

-    new Cologne.Logger.Console({
-      formatter: new Cologne.Formatter.Token({
+    new Loggers.Console({
+      formatter: new Formatters.Token({

         formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
       })
     })
         formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
       })
     })


@@ -35,10 +32,6 @@ let co = new Cologne({
 This example would create a cologne instance with a console logger that
 uses a Token formatter. (More on 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.);
 

-## Do I need anything special?
-
-Node 4.0+
-

 ## Quick API Reference
 
 * **addLogger(logger)**: Adds a logger to the cologne instance.
 ## Quick API Reference
 
 * **addLogger(logger)**: Adds a logger to the cologne instance.


@@ -55,48 +48,48 @@ Node 4.0+
 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
 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.
+to the browser console.

 
 

-`#log()` will receive any number of `Cologne Log Objects`. To see what
-this format includes, check further below.
+`#log()` will receive any number of `Cologne Log Objects`. For a detailed
+reference of this format, see further below.

 
 

-We include two loggers out of the box:
+Cologne includes two loggers out of the box:

 
 

-* `Cologne.Logger.Console` logs to the JS console
-* `Cologne.Logger.File` appends to a file
+* `Loggers.Console` logs to the JS console
+* `Loggers.File` appends to a file

 
 

-### Cologne.Logger.Console
+### Loggers.Console

 
 

-This logger communicates the Javascript console. It uses the log level
+This logger communicates with 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 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
+to the `#format()` method: it should receive a cologne log object and respond

 with a string.
 
 ```javascript
 with a string.
 
 ```javascript

-new Cologne.Logger.Console({
-  formatter : new Cologne.Formatter.Token({
+new Loggers.Console({
+  formatter : new Formatters.Token({

     formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
   })
 });
 ```
 
     formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
   })
 });
 ```
 

-### Cologne.Logger.File
+### Loggers.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.
 
 
 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.
+It MUST include a `file` property on initialization, otherwise it will throw
+an exception.

 
 ```javascript
 
 ```javascript

-new Cologne.Logger.File({
+new Loggers.File({

   file: '/var/log/server_log.log',
   file: '/var/log/server_log.log',

-  formatter : new Cologne.Formatter.Token({
-    formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
+  formatter : new Formatters.Token({
+    formatString: '[{{_ansi:_level}}{{_timestamp}}{{_ansi:reset}}]{{_from}}: {{message}}'

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


@@ -106,24 +99,23 @@ new Cologne.Logger.File({
 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.
 
 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.
 

-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
 to `#log()` is a valid logger:
 
 ```javascript
 // A valid, very minimalistic logger
 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()` is a valid logger:
 
 ```javascript
 // A valid, very minimalistic logger

-let simpleLogger = {
-  log : function () {
-    for (let logObject of arguments) {
-      this._doSomeMagic(logObject);
+const simpleLogger = {
+  log: function(...logs) {
+
+    for (const log of logs) {
+      this._doSomeMagic(logs);

     }
   },
 
     }
   },
 

-  _doSomeMagic : function (logObject) {
-    console.log(logObject + "... but magical!");
+  _doSomeMagic: function(log) {
+
+    console.log(log + "... but magical!");

   }
 };
 
   }
 };
 


@@ -134,20 +126,20 @@ logger.addLogger(simpleLogger);
 ## Formatters
 
 Cologne doesn't need formatters to work, and in fact they're optional in
 ## 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,
+the included loggers. 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
 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.
+it should return a string.

 
 We include some formatters so you can get running real quicklike:
 
 
 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
+* `Formatters.Simple` a simple predefined formatter
+* `Formatters.Token` a formatter that lets you define format

   strings that it will use to build your final log.
 
   strings that it will use to build your final log.
 

-### Cologne.Formatter.Simple
+### Formatters.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:


@@ -163,13 +155,14 @@ Where `_timestamp` is converted to ISO.
 * `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
 * `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.
+formatter will add a bit of color in the level string. Red for error, crit,
+alert, and emerg; yellow for warn; blue for info; green for debug; and white
+for everything else.

 
 #### Usage
 
 ```javascript
 
 #### Usage
 
 ```javascript

-new Cologne.Formatter.Simple({
+new Formatters.Simple({

   colorize: true
 });
 ```
   colorize: true
 });
 ```


@@ -181,7 +174,7 @@ co.log("hello world");
 // -> [2016-01-21T05:50:36.505Z][INFO] Server Logger: hello world
 ```
 
 // -> [2016-01-21T05:50:36.505Z][INFO] Server Logger: hello world
 ```
 

-### Cologne.Formatter.Token
+### Formatters.Token

 
 The token formatter lets you build strings with simple tokens. When
 instantiating, you can specify a `formatString` to interpolate
 
 The token formatter lets you build strings with simple tokens. When
 instantiating, you can specify a `formatString` to interpolate


@@ -200,7 +193,7 @@ you don't like it, you can specify your own.
 #### Usage
 
 ```javascript
 #### Usage
 
 ```javascript

-new Cologne.Formatter.Token({
+new Formatters.Token({

   formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
 });
 ```
   formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
 });
 ```


@@ -237,36 +230,35 @@ returns a string.
 Here's an example of a logger that surrounds a log with sparkles:
 
 ```javascript
 Here's an example of a logger that surrounds a log with sparkles:
 
 ```javascript

-var simpleFormatter = {
-  format : function (logObject) {
-    return '✨' + logObject.message + '✨';
+const sparkleFormatter = {
+  format: function(logObject) {
+
+    return `✨${logObject.message}✨`;

   }
 }
 
   }
 }
 

-logger.addLogger(new Cologne.Logger.Console({
-  formatter: simpleFormatter
+logger.addLogger(new Loggers.Console({
+  formatter: sparkleFormatter

 }));
 ```
 
 ## The Cologne Log Format
 
 The cologne log format is a JSON based log format, based on the cobalt
 }));
 ```
 
 ## 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
+log format, which is in turn based on Graylog's GELF. However, where GELF

 treats all internal fields without a prefix, and all user fields with a
 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.
+prefix, we do it backwards so it's easier to extend the object with
+metadata from existing objects.

 
 You could try to build it on your own, but you can use `#buildLog()`
 to build it without logging.
 
 ### Fields
 
 
 You could try to build it on your own, but you can use `#buildLog()`
 to build it without logging.
 
 ### Fields
 

-* **\_timestamp** : A timestamp in miliseconds with fractions of a second
-  in the floating point area.
+* **\_timestamp** : A bigint timestamp in nanoseconds

 * **\_cologneLog** <String> : This is how we know if the log is already
   formatted and ready to go. This field is a string containing the
 * **\_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.
+  version of cologne log format it's using. It's `2.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 ->
 * **\_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 ->


@@ -295,6 +287,3 @@ only reports error or worse.)
 * Improve the API for buildLog
 * More loggers & formatters (will not be distributed in core cologne)
 * Improve tests
 * 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