]> git.r.bdr.sh - rbdr/cologne/blame - README.md
Handles null log
[rbdr/cologne] / README.md
CommitLineData
87881a5c 1# Cobalt #
08ce17a6 2
941d0901
BB
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.
87881a5c
BB
9
10Example of instantiating a cobalt logger:
11
2aa083b6
BB
12In node:
13```
3a563eb4 14require('cobalt-log');
2aa083b6
BB
15```
16
17In the browser just require the files. Then:
18
87881a5c
BB
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
941d0901
BB
32This code will create an instance with a JsConsole logger that uses the
33Token formatter (See loggers and formatters below).
87881a5c 34
941d0901
BB
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)
87881a5c
BB
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.
941d0901
BB
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.
87881a5c 47* **buildSeparator**: Generates a cobalt log object that defines a separator
941d0901
BB
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.
87881a5c
BB
52* **space(lines)**: Logs an empty string `lines` times
53* **indent()**: Increases the indent level globally.
941d0901
BB
54* **indent(callback)**: Increases the indent level for anything logged
55 from inside the callback.
87881a5c
BB
56* **outdent()/outdent(callback)**: Same as indent, but decreases indent level.
57* **color()**: Changes the color globally. †
941d0901
BB
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.
87881a5c 62
941d0901
BB
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.
87881a5c
BB
67
68
69## Loggers ##
70
941d0901
BB
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.
87881a5c
BB
77
78
79### Cobalt.Logger.JsConsole ###
80
941d0901
BB
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:
87881a5c
BB
85
86```
87 new Cobalt.Logger.JsConsole({
88 formatter : Cobalt.Formatter.Token,
89 formatterOpts : {
90 formatString : "[{{_timestamp}}] {{message}} (@{{_from}})"
91 }
92 })
93```
94
941d0901
BB
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.
87881a5c 99
2e7f5498
BB
100### Cobalt.Logger.File ###
101
102This logger communicates a file via a writable stream, and is intended
103only for node. Like the JSConsole logger, you can also initialize it with
104a 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
115What this does is: it will trigger the method `format` on `formatter`
116passing the `logObject` and `formatterOpts`. This means that a formatter is
117any object that responds to `format(logObject, formatterOpts)`. It expects
118a string to be returned.
119
87881a5c
BB
120### Cobalt.Logger.Socket ###
121
941d0901
BB
122This logger sends the log object to a socket using Socket.IO. It does not
123format the output. To catch the log from the recipient, you have to listen
124for the `log` event, and from there you can pass it to another Cobalt
125instance or do whatever you want with it.
87881a5c
BB
126
127### More Loggers? ###
128
941d0901
BB
129You can build your own logger easily for any method of transport you find
130necessary (e.g. mail, database, twitter, etc). Any object that responds
131to `#log(logObject)` is a valid logger:
87881a5c
BB
132
133```javascript
134// A valid, very minimalistic logger
135var simpleLogger = {
136 log : function (logObject) {
137 console.log(logObject.message);
138 }
139}
140
141logger.addLogger(simpleLogger);
142```
143
144## Formatters ##
145
941d0901
BB
146Cobalt itself makes no assumptions about the output of the logger and just
147passes the object to every logger it has. However, it is clear that loggers
148may want to manipulate this object. As shown in the JsConsole, a formatter
149should 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
2e7f5498 151recommendation (as this is the way the included JsConsole/File loggers do it)
941d0901 152and it is up to the logger on how to transform the object it receives.
2e7f5498
BB
153
154### Cobalt.Formatter.Simple ###
155
156This is the lazy formatter, it just outputs the string in the following
157format:
158
159```
160'[{{_timestamp}}][{{_logLevelString}}]{{_from}}: {{_message}}'
161```
162
163Where `_timestamp` is converted to ISO.
164
165Example output:
166
167```
168cobalt.log("hello world");
169// -> [2015-01-09T16:02:23.102Z][INFO] Generic Cobalt Logger : hello world
170```
87881a5c
BB
171
172### Cobalt.Formatter.Token ###
173
2e7f5498
BB
174The Token formatter is a more advanced, but still fairly simple
175formatter. It takes a `formatString` and interpolates the properties
176of the object. By default it transforms anything inside double curly
177braces `{{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`
87881a5c
BB
191
192#### Options ####
193
941d0901
BB
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`)
87881a5c
BB
202
203### More Formatters? ###
204
941d0901
BB
205As with loggers, cobalt itself does not worry about these things. However,
206if you wish to make a formatter that is exchangable with Token, you just
207need to create an object that responds to the`format(logObject, optionsObject)`
208method:
87881a5c
BB
209
210```javascript
211// A valid, very minimalistic formatter
212var 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
222logger.addLogger(new Cobalt.Logger.JsConsole({
223 formatter: simpleFormatter,
224 formatterOpts : {
225 showDate : true
226 }
227}));
228```
229
230## The Cobalt Log Format ##
231
941d0901
BB
232The Cobalt Log (CoLog) format is a JSON based log format used with cobalt.
233It is partly inspired in Greylog's GELF format, but with very notorious
234differences. The CoLog requires a header with certain fields that allow
235cobalt and its pieces to handle it. All header fields are prefixed with
236an underscore. Other than those fields, you can put whatever you want in
237the object; It's up to the loggers to make sense of the structure and
238display it in a way that makes sense.
239
240You can attempt to build this structure on your own, or let cobalt build it for
241you. Any object you pass for logging will be converted. However, if you
242build it on your own you have two options: The first one is use buildLog
243to create a log object for "item" as if you had logged "item" or you can
244use extendLog that will create a dummy log object and extends it with
245whatever object you pass to it.
87881a5c
BB
246
247### Required Fields ###
248
249* **_version** : The version of cobalt this is designed to work with
250* **_timestamp** : A timestamp in microseconds.
941d0901
BB
251* **_cobaltLog** [true] : Cobalt will check for the \_cobaltLog to decide if
252transformation will happen or not.
87881a5c
BB
253
254### Optional Fields ###
255
941d0901
BB
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.