X-Git-Url: https://git.r.bdr.sh/rbdr/cologne/blobdiff_plain/08ce17a6d30a2f40459a4eecc7db20e1931046f9..5c03d3b44c5daeb34180c6922fcf3307f1217cbc:/README.md diff --git a/README.md b/README.md index 618bae4..b162346 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,212 @@ -# cobalt.js # +# Cobalt # -Experiments with cobalt in javascript. +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. + +Example of instantiating a cobalt logger: + +In node: +``` +Cobalt = require('cobalt-log'); +``` + +In the browser just require the files. Then: + +``` +this.logger = new Cobalt.Console({ + from : "Breezi Client", + loggers : [ new Cobalt.Logger.JsConsole({ + formatter : Cobalt.Formatter.Token, + formatterOpts : { + formatString : "{{_from}}: {{message}}", + ansiColor : true + } + })] +}); +``` + +This code will create an instance with a JsConsole logger that uses the +Token formatter (See 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) + +## Quick API Reference ## + +* **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 +* **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}})" + } + }) +``` + +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. + +### Cobalt.Logger.Socket ### + +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. + +### More Loggers? ### + +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: + +```javascript +// A valid, very minimalistic logger +var simpleLogger = { + log : function (logObject) { + console.log(logObject.message); + } +} + +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 logger does it) +and it is up to the logger on how to transform the object it receives. +Cobalt includes a very simple formatter that works well in conjuction +with JsConsole. + +### Cobalt.Formatter.Token ### + +The Token formatter is a very simple formatter that uses a formatString to +extract values from the log object and interpolate them in a string. + +#### 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: + +```javascript +// A valid, very minimalistic formatter +var simpleFormatter = { + format : function (logObject, options) { + if (options.showDate) { + return "[" + Date(logObject._timeStamp) + "] " + logObject.message + } else { + return logObject.message; + } + } +} + +logger.addLogger(new Cobalt.Logger.JsConsole({ + formatter: simpleFormatter, + formatterOpts : { + showDate : true + } +})); +``` + +## The Cobalt Log Format ## + +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 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. + +### Required Fields ### + +* **_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. + +### Optional Fields ### + +* **\_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.