]> git.r.bdr.sh - rbdr/cologne/blame_incremental - README.md
Update readme, remove event_trackerstuffs
[rbdr/cologne] / README.md
... / ...
CommitLineData
1# Cobalt #
2
3Cobalt 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.
4
5Example of instantiating a cobalt logger:
6
7In node:
8```
9Cobalt = require('cobalt-log');
10```
11
12In the browser just require the files. Then:
13
14```
15this.logger = new Cobalt.Console({
16 from : "Breezi Client",
17 loggers : [ new Cobalt.Logger.JsConsole({
18 formatter : Cobalt.Formatter.Token,
19 formatterOpts : {
20 formatString : "{{_from}}: {{message}}",
21 ansiColor : true
22 }
23 })]
24});
25```
26
27This code will create an instance with a JsConsole logger that uses the Token formatter (See loggers and formatters below).
28
29Cobalt 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)
30
31## Quick API Reference ##
32
33* **addLogger(logger)**: Adds a logger to the cobalt instance.
34* **removeLogger(logger)**: Removes a logger from the cobalt instance.
35* **buildLog(item, level=7)**: Generates a cobalt log object (it will do this automatically when you log anything)
36* **buildSeparator**: Generates a cobalt log object that defines a separator
37* **log, info, notice, warn, error**: Generates a log object with the appropriate severity level and sends it to all loggers.
38* **separator()**: Generates a separator log object and sends it to all loggers.
39* **space(lines)**: Logs an empty string `lines` times
40* **indent()**: Increases the indent level globally.
41* **indent(callback)**: Increases the indent level for anything logged from inside the callback.
42* **outdent()/outdent(callback)**: Same as indent, but decreases indent level.
43* **color()**: Changes the color globally. †
44* **color(callback)**: Changes the color for anything logged from inside the callback. †
45* **now()**: Returns the current time in microseconds, using performance.now() or process.hrtime() if available. If not, falls back to miliseconds.
46
47† 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.
48
49
50## Loggers ##
51
52Cobalt 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.
53
54
55### Cobalt.Logger.JsConsole ###
56
57This 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:
58
59```
60 new Cobalt.Logger.JsConsole({
61 formatter : Cobalt.Formatter.Token,
62 formatterOpts : {
63 formatString : "[{{_timestamp}}] {{message}} (@{{_from}})"
64 }
65 })
66```
67
68What 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.
69
70### Cobalt.Logger.Socket ###
71
72This 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.
73
74### More Loggers? ###
75
76You 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:
77
78```javascript
79// A valid, very minimalistic logger
80var simpleLogger = {
81 log : function (logObject) {
82 console.log(logObject.message);
83 }
84}
85
86logger.addLogger(simpleLogger);
87```
88
89## Formatters ##
90
91Cobalt 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.
92
93### Cobalt.Formatter.Token ###
94
95The Token formatter is a very simple formatter that uses a formatString to extract values from the log object and interpolate them in a string.
96
97#### Options ####
98
99* **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}}"`)
100* **ansiColor**: A boolean value, when `true` will output the string in ANSI color depending on the severity level (defaults to `false`)
101
102### More Formatters? ###
103
104As 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:
105
106```javascript
107// A valid, very minimalistic formatter
108var simpleFormatter = {
109 format : function (logObject, options) {
110 if (options.showDate) {
111 return "[" + Date(logObject._timeStamp) + "] " + logObject.message
112 } else {
113 return logObject.message;
114 }
115 }
116}
117
118logger.addLogger(new Cobalt.Logger.JsConsole({
119 formatter: simpleFormatter,
120 formatterOpts : {
121 showDate : true
122 }
123}));
124```
125
126## The Cobalt Log Format ##
127
128The 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.
129
130You 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.
131
132### Required Fields ###
133
134* **_version** : The version of cobalt this is designed to work with
135* **_timestamp** : A timestamp in microseconds.
136* **_cobaltLog** [true] : Cobalt will check for the _cobaltLog to decide if transformation will happen or not.
137
138### Optional Fields ###
139
140* **_from**: The sender of the log (Defaults to Generic Cobalt Logger)
141* **_level**: The level of the log (Defaults to 7)
142* **_levelString**: The string corresponding to the log level (e.g. 7 -> DEBUG, 3 -> ERROR, 0 -> CRIT)
143* **_indentLevel**: The indent level of the log
144* **_color**: The color of the log
145* **_separator**: If true, indicates that this is a separator and holds no valuable information.