git.r.bdr.sh - rbdr/cologne/blob - README.md

   1 # Cobalt #
   2
   3 Cobalt is a simple logger multiplexer that works with a JSON based format.
   4 You can instantiate it with a set of loggers or add them later
   5 (see API reference below). When logging anything, Cobalt will attempt to
   6 generate an Object that conforms to the Cobalt Log Format Definition
   7 (if required) and passes it to every logger it has by calling their `log`
   8 method.
   9
  10 Example of instantiating a cobalt logger:
  11
  12 In node:
  13 ```
  14 require('cobalt-log');
  15 ```
  16
  17 In the browser just require the files. Then:
  18
  19 ```
  20 this.logger = new Cobalt.Console({
  21   from : "Breezi Client",
  22   loggers : [ new Cobalt.Logger.JsConsole({
  23               formatter : Cobalt.Formatter.Token,
  24               formatterOpts : {
  25                 formatString : "{{_from}}: {{message}}",
  26                 ansiColor : true
  27               }
  28             })]
  29 });
  30 ```
  31
  32 This code will create an instance with a JsConsole logger that uses the
  33 Token formatter (See loggers and formatters below).
  34
  35 Cobalt works in a browser or inside node, so feel free to use cobalt all
  36 over! (Also, see the socket logger below for info on connecting cobalt
  37 loggers)
  38
  39 ## Quick API Reference ##
  40
  41 * **addLogger(logger)**: Adds a logger to the cobalt instance.
  42 * **removeLogger(logger)**: Removes a logger from the cobalt instance.
  43 * **buildLog(item, level=7)**: Generates a cobalt log object as if you had
  44   logged item (it will do this automatically when you log anything)
  45 * **extendLog(object)**: Creates a dummy log object and extends it with
  46   object.
  47 * **buildSeparator**: Generates a cobalt log object that defines a separator
  48 * **log, info, notice, warn, error**: Generates a log object with the
  49   appropriate severity level and sends it to all loggers.
  50 * **separator()**: Generates a separator log object and sends it to all
  51   loggers.
  52 * **space(lines)**: Logs an empty string `lines` times
  53 * **indent()**: Increases the indent level globally.
  54 * **indent(callback)**: Increases the indent level for anything logged
  55   from inside the callback.
  56 * **outdent()/outdent(callback)**: Same as indent, but decreases indent level.
  57 * **color()**: Changes the color globally. †
  58 * **color(callback)**: Changes the color for anything logged from inside the
  59   callback. †
  60 * **now()**: Returns the current time in microseconds, using performance.now()
  61   or process.hrtime() if available. If not, falls back to miliseconds.
  62
  63 † Cobalt doesn't really care about formatting or colors, but it allows you
  64 to set the `_color` property in the generated object. In the end, it's up to
  65 the formatter to decide if it will use this property. However, this maintains
  66 the old cobalt API and gives you flexibility in how you color your logs.
  67
  68
  69 ## Loggers ##
  70
  71 Cobalt doesn't depend on any particular logger, and the loggers it expects
  72 to receive is any object that responds to the log method. However, since it
  73 would pass a JSON object instead of a string, this may result in unexpected
  74 behavior for loggers that don't expect it. To ease the use of Cobalt with
  75 existing loggers, cobalt includes a couple of loggers that you can use out
  76 of the box.
  77
  78
  79 ### Cobalt.Logger.JsConsole ###
  80
  81 This logger communicates the Javascript console present in web browsers or
  82 node with cobalt. It uses the logLevel to trigger the appropriate method
  83 (e.g. info vs warn vs error). You can also initialize it with a formatter,
  84 to convert the log object to a string:
  85
  86 ```
  87  new Cobalt.Logger.JsConsole({
  88      formatter : Cobalt.Formatter.Token,
  89      formatterOpts : {
  90          formatString : "[{{_timestamp}}] {{message}} (@{{_from}})"
  91      }
  92  })
  93 ```
  94
  95 What this does is: it will trigger the method `format` on `formatter`
  96 passing the `logObject` and `formatterOpts`. This means that a formatter is
  97 any object that responds to `format(logObject, formatterOpts)`. It expects
  98 a string to be returned.
  99
 100 ### Cobalt.Logger.File ###
 101
 102 This logger communicates a file via a writable stream, and is intended
 103 only for node. Like the JSConsole logger, you can also initialize it with
 104 a formatter to convert the log object to a string:
 105
 106 ```
 107  new Cobalt.Logger.File({
 108      formatter : Cobalt.Formatter.Token,
 109      formatterOpts : {
 110          formatString : "[{{_timestamp}}] {{message}} (@{{_from}})"
 111      }
 112  })
 113 ```
 114
 115 What this does is: it will trigger the method `format` on `formatter`
 116 passing the `logObject` and `formatterOpts`. This means that a formatter is
 117 any object that responds to `format(logObject, formatterOpts)`. It expects
 118 a string to be returned.
 119
 120 ### Cobalt.Logger.Socket ###
 121
 122 This logger sends the log object to a socket using Socket.IO. It does not
 123 format the output. To catch the log from the recipient, you have to listen
 124 for the `log` event, and from there you can pass it to another Cobalt
 125 instance or do whatever you want with it.
 126
 127 ### More Loggers? ###
 128
 129 You can build your own logger easily for any method of transport you find
 130 necessary (e.g. mail, database, twitter, etc). Any object that responds
 131 to `#log(logObject)` is a valid logger:
 132
 133 ```javascript
 134 // A valid, very minimalistic logger
 135 var simpleLogger = {
 136   log : function (logObject) {
 137     console.log(logObject.message);
 138   }
 139 }
 140
 141 logger.addLogger(simpleLogger);
 142 ```
 143
 144 ## Formatters ##
 145
 146 Cobalt itself makes no assumptions about the output of the logger and just
 147 passes the object to every logger it has. However, it is clear that loggers
 148 may want to manipulate this object. As shown in the JsConsole, a formatter
 149 should respond to the format method and receive a `logObject` and an
 150 `optsObject`. However, as this is not a core part of Cobalt, this is only a
 151 recommendation (as this is the way the included JsConsole/File loggers do it)
 152 and it is up to the logger on how to transform the object it receives.
 153
 154 ### Cobalt.Formatter.Simple ###
 155
 156 This is the lazy formatter, it just outputs the string in the following
 157 format:
 158
 159 ```
 160 '[{{_timestamp}}][{{_logLevelString}}]{{_from}}: {{_message}}'
 161 ```
 162
 163 Where `_timestamp` is converted to ISO.
 164
 165 Example output:
 166
 167 ```
 168 cobalt.log("hello world");
 169 // -> [2015-01-09T16:02:23.102Z][INFO] Generic Cobalt Logger : hello world
 170 ```
 171
 172 ### Cobalt.Formatter.Token ###
 173
 174 The Token formatter is a more advanced, but still fairly simple
 175 formatter. It takes a `formatString` and interpolates the properties
 176 of the object. By default it transforms anything inside double curly
 177 braces `{{likeThis}}`, however you can set a custom `replaceRule`.
 178
 179 #### Accepted Options ####
 180
 181 * `formatString` : The string used to replace. Defaults to `"{{message}}"`
 182 * `replaceRule` : The regex rule to use for replacement of tokens in the
 183   formatString. Defaults to `/{{(.*?)}}/g`
 184 * `separatorLength` <Number> : How long to print separators. Defaults to 60.
 185 * `isoDate` <Boolean> : Whether or not to convert `_timestamp` to ISO
 186   date. Defaults to true.
 187 * `separatorType` <String> : The string to use for the separator.
 188   Defaults to `"="`
 189 * `ansiColor` <Boolean> : Whether to use ANSI colors for output.
 190   Defaults to `false`. This options depends on `colors`
 191
 192 #### Options ####
 193
 194 * **formatString**: A string that defines the format of the output. It is a
 195   string with double curly braces denoting fields. For example:
 196   `"[{{_timestamp}}] {{message}} (@{{_from}})"` would attempt to extract the
 197   \_timestamp, message and \_from fields to create a string similar to this:
 198   `"[124896126491.123] Testing the logger (@Client Application)"`
 199   (defaults to `"{{message}}"`)
 200 * **ansiColor**: A boolean value, when `true` will output the string in ANSI
 201   color depending on the severity level (defaults to `false`)
 202
 203 ### More Formatters? ###
 204
 205 As with loggers, cobalt itself does not worry about these things. However,
 206 if you wish to make a formatter that is exchangable with Token, you just
 207 need to create an object that responds to the`format(logObject, optionsObject)`
 208 method:
 209
 210 ```javascript
 211 // A valid, very minimalistic formatter
 212 var simpleFormatter = {
 213   format : function (logObject, options) {
 214     if (options.showDate) {
 215       return "[" + Date(logObject._timeStamp) + "] " + logObject.message
 216     } else {
 217       return logObject.message;
 218     }
 219   }
 220 }
 221
 222 logger.addLogger(new Cobalt.Logger.JsConsole({
 223   formatter: simpleFormatter,
 224   formatterOpts : {
 225     showDate : true
 226   }
 227 }));
 228 ```
 229
 230 ## The Cobalt Log Format ##
 231
 232 The Cobalt Log (CoLog) format is a JSON based log format used with cobalt.
 233 It is partly inspired in Greylog's GELF format, but with very notorious
 234 differences. The CoLog requires a header with certain fields that allow
 235 cobalt and its pieces to handle it. All header fields are prefixed with
 236 an underscore. Other than those fields, you can put whatever you want in
 237 the object; It's up to the loggers to make sense of the structure and
 238 display it in a way that makes sense.
 239
 240 You can attempt to build this structure on your own, or let cobalt build it for
 241 you. Any object you pass for logging will be converted. However, if you
 242 build it on your own you have two options: The first one is use buildLog
 243 to create a log object for "item" as if you had logged "item" or you can
 244 use extendLog that will create a dummy log object and extends it with
 245 whatever object you pass to it.
 246
 247 ### Required Fields ###
 248
 249 * **_version** : The version of cobalt this is designed to work with
 250 * **_timestamp** : A timestamp in microseconds.
 251 * **_cobaltLog** [true] : Cobalt will check for the \_cobaltLog to decide if
 252 transformation will happen or not.
 253
 254 ### Optional Fields ###
 255
 256 * **\_from**: The sender of the log (Defaults to Generic Cobalt Logger)
 257 * **\_level**: The level of the log (Defaults to 7)
 258 * **\_levelString**: The string corresponding to the log level (e.g. 7 ->
 259   DEBUG, 3 -> ERROR, 0 -> CRIT)
 260 * **\_indentLevel**: The indent level of the log
 261 * **\_color**: The color of the log
 262 * **\_separator**: If true, indicates that this is a separator and holds no
 263   valuable information.