]> git.r.bdr.sh - rbdr/cologne/blame_incremental - README.md
Makes the simple formatter useful
[rbdr/cologne] / README.md
... / ...
CommitLineData
1# Cobalt #
2
3Cobalt is a simple logger multiplexer that works with a JSON based format.
4You can instantiate it with a set of loggers or add them later
5(see API reference below). When logging anything, Cobalt will attempt to
6generate 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`
8method.
9
10Example of instantiating a cobalt logger:
11
12In node:
13```
14require('cobalt-log');
15```
16
17In the browser just require the files. Then:
18
19```
20this.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
32This code will create an instance with a JsConsole logger that uses the
33Token formatter (See loggers and formatters below).
34
35Cobalt works in a browser or inside node, so feel free to use cobalt all
36over! (Also, see the socket logger below for info on connecting cobalt
37loggers)
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
64to set the `_color` property in the generated object. In the end, it's up to
65the formatter to decide if it will use this property. However, this maintains
66the old cobalt API and gives you flexibility in how you color your logs.
67
68
69## Loggers ##
70
71Cobalt doesn't depend on any particular logger, and the loggers it expects
72to receive is any object that responds to the log method. However, since it
73would pass a JSON object instead of a string, this may result in unexpected
74behavior for loggers that don't expect it. To ease the use of Cobalt with
75existing loggers, cobalt includes a couple of loggers that you can use out
76of the box.
77
78
79### Cobalt.Logger.JsConsole ###
80
81This logger communicates the Javascript console present in web browsers or
82node 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,
84to 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
95What this does is: it will trigger the method `format` on `formatter`
96passing the `logObject` and `formatterOpts`. This means that a formatter is
97any object that responds to `format(logObject, formatterOpts)`. It expects
98a string to be returned.
99
100### Cobalt.Logger.Socket ###
101
102This logger sends the log object to a socket using Socket.IO. It does not
103format the output. To catch the log from the recipient, you have to listen
104for the `log` event, and from there you can pass it to another Cobalt
105instance or do whatever you want with it.
106
107### More Loggers? ###
108
109You can build your own logger easily for any method of transport you find
110necessary (e.g. mail, database, twitter, etc). Any object that responds
111to `#log(logObject)` is a valid logger:
112
113```javascript
114// A valid, very minimalistic logger
115var simpleLogger = {
116 log : function (logObject) {
117 console.log(logObject.message);
118 }
119}
120
121logger.addLogger(simpleLogger);
122```
123
124## Formatters ##
125
126Cobalt itself makes no assumptions about the output of the logger and just
127passes the object to every logger it has. However, it is clear that loggers
128may want to manipulate this object. As shown in the JsConsole, a formatter
129should respond to the format method and receive a `logObject` and an
130`optsObject`. However, as this is not a core part of Cobalt, this is only a
131recommendation (as this is the way the included JsConsole logger does it)
132and it is up to the logger on how to transform the object it receives.
133Cobalt includes a very simple formatter that works well in conjuction
134with JsConsole.
135
136### Cobalt.Formatter.Token ###
137
138The Token formatter is a very simple formatter that uses a formatString to
139extract values from the log object and interpolate them in a string.
140
141#### Options ####
142
143* **formatString**: A string that defines the format of the output. It is a
144 string with double curly braces denoting fields. For example:
145 `"[{{_timestamp}}] {{message}} (@{{_from}})"` would attempt to extract the
146 \_timestamp, message and \_from fields to create a string similar to this:
147 `"[124896126491.123] Testing the logger (@Client Application)"`
148 (defaults to `"{{message}}"`)
149* **ansiColor**: A boolean value, when `true` will output the string in ANSI
150 color depending on the severity level (defaults to `false`)
151
152### More Formatters? ###
153
154As with loggers, cobalt itself does not worry about these things. However,
155if you wish to make a formatter that is exchangable with Token, you just
156need to create an object that responds to the`format(logObject, optionsObject)`
157method:
158
159```javascript
160// A valid, very minimalistic formatter
161var simpleFormatter = {
162 format : function (logObject, options) {
163 if (options.showDate) {
164 return "[" + Date(logObject._timeStamp) + "] " + logObject.message
165 } else {
166 return logObject.message;
167 }
168 }
169}
170
171logger.addLogger(new Cobalt.Logger.JsConsole({
172 formatter: simpleFormatter,
173 formatterOpts : {
174 showDate : true
175 }
176}));
177```
178
179## The Cobalt Log Format ##
180
181The Cobalt Log (CoLog) format is a JSON based log format used with cobalt.
182It is partly inspired in Greylog's GELF format, but with very notorious
183differences. The CoLog requires a header with certain fields that allow
184cobalt and its pieces to handle it. All header fields are prefixed with
185an underscore. Other than those fields, you can put whatever you want in
186the object; It's up to the loggers to make sense of the structure and
187display it in a way that makes sense.
188
189You can attempt to build this structure on your own, or let cobalt build it for
190you. Any object you pass for logging will be converted. However, if you
191build it on your own you have two options: The first one is use buildLog
192to create a log object for "item" as if you had logged "item" or you can
193use extendLog that will create a dummy log object and extends it with
194whatever object you pass to it.
195
196### Required Fields ###
197
198* **_version** : The version of cobalt this is designed to work with
199* **_timestamp** : A timestamp in microseconds.
200* **_cobaltLog** [true] : Cobalt will check for the \_cobaltLog to decide if
201transformation will happen or not.
202
203### Optional Fields ###
204
205* **\_from**: The sender of the log (Defaults to Generic Cobalt Logger)
206* **\_level**: The level of the log (Defaults to 7)
207* **\_levelString**: The string corresponding to the log level (e.g. 7 ->
208 DEBUG, 3 -> ERROR, 0 -> CRIT)
209* **\_indentLevel**: The indent level of the log
210* **\_color**: The color of the log
211* **\_separator**: If true, indicates that this is a separator and holds no
212 valuable information.