]>
Commit | Line | Data |
---|---|---|
87881a5c | 1 | # Cobalt # |
08ce17a6 | 2 | |
941d0901 BB |
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. | |
87881a5c BB |
9 | |
10 | Example of instantiating a cobalt logger: | |
11 | ||
2aa083b6 BB |
12 | In node: |
13 | ``` | |
3a563eb4 | 14 | require('cobalt-log'); |
2aa083b6 BB |
15 | ``` |
16 | ||
17 | In the browser just require the files. Then: | |
18 | ||
87881a5c BB |
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 | ||
941d0901 BB |
32 | This code will create an instance with a JsConsole logger that uses the |
33 | Token formatter (See loggers and formatters below). | |
87881a5c | 34 | |
941d0901 BB |
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) | |
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 |
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. | |
87881a5c BB |
67 | |
68 | ||
69 | ## Loggers ## | |
70 | ||
941d0901 BB |
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. | |
87881a5c BB |
77 | |
78 | ||
79 | ### Cobalt.Logger.JsConsole ### | |
80 | ||
941d0901 BB |
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: | |
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 |
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. | |
87881a5c | 99 | |
2e7f5498 BB |
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 | ||
87881a5c BB |
120 | ### Cobalt.Logger.Socket ### |
121 | ||
941d0901 BB |
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. | |
87881a5c BB |
126 | |
127 | ### More Loggers? ### | |
128 | ||
941d0901 BB |
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: | |
87881a5c BB |
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 | ||
941d0901 BB |
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 | |
2e7f5498 | 151 | recommendation (as this is the way the included JsConsole/File loggers do it) |
941d0901 | 152 | and it is up to the logger on how to transform the object it receives. |
2e7f5498 BB |
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 | ``` | |
87881a5c BB |
171 | |
172 | ### Cobalt.Formatter.Token ### | |
173 | ||
2e7f5498 BB |
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` | |
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 |
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: | |
87881a5c BB |
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 | ||
941d0901 BB |
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. | |
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 |
252 | transformation 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. |