X-Git-Url: https://git.r.bdr.sh/rbdr/cologne/blobdiff_plain/bfd26c004f1bbc07f049013ab4e8de970e14341f..b9c7f5bfb5b4693b0644c01bd36500eb20e3f33a:/README.md?ds=inline diff --git a/README.md b/README.md index bf2ae2d..6772648 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,27 @@ # Cologne -![https://david-dm.org/rbdr/cologne.svg][dependencies-shield] -![https://circleci.com/gh/rbdr/cologne.svg?style=shield][circle-ci-shield] - -Cologne is a logger multiplexer that works mainly with a JSON format. It -can be instantiated with several loggers, or they can be changed after +Cologne is a logger multiplexer that uses a JSON log format inspired in gelf. +It can be instantiated with several loggers, or they can be changed after the fact. ## Usage -Install from npm or add to your package.json: +Install from npm ``` -$ npm install cologne +$ npm install --save cologne ``` -Create an instance: +Create an instance ```javascript -require('cologne'); +const { Cologne, Loggers, Formatters } = require('cologne'); -let co = new Cologne({ - from: "Special Worker Logger", +const co = new Cologne({ + from: 'Special Worker Logger', loggers: [ - new Cologne.Logger.Console({ - formatter: new Cologne.Formatter.Token({ + new Loggers.Console({ + formatter: new Formatters.Token({ formatString: '[{{_timestamp}}]{{_from}}: {{message}}' }) }) @@ -35,10 +32,6 @@ let co = new Cologne({ This example would create a cologne instance with a console logger that uses a Token formatter. (More on loggers and formatters below.); -## Do I need anything special? - -Node 4.0+ - ## Quick API Reference * **addLogger(logger)**: Adds a logger to the cologne instance. @@ -55,48 +48,48 @@ Node 4.0+ Cologne loggers are any object that responds to the `#log()` method. This methoud should be able to receive any number of arguments and log them independently. Similar to how you can send multiple arguments -to the JS console. +to the browser console. -`#log()` will receive any number of `Cologne Log Objects`. To see what -this format includes, check further below. +`#log()` will receive any number of `Cologne Log Objects`. For a detailed +reference of this format, see further below. -We include two loggers out of the box: +Cologne includes two loggers out of the box: -* `Cologne.Logger.Console` logs to the JS console -* `Cologne.Logger.File` appends to a file +* `Loggers.Console` logs to the JS console +* `Loggers.File` appends to a file -### Cologne.Logger.Console +### Loggers.Console -This logger communicates the Javascript console. It uses the log level +This logger communicates with the Javascript console. It uses the log level to trigger the appropriate method, so `error` logs would go to stderr as expected when calling `console.error`. This logger can be sent a `formatter`, which is an object that responds -to the `#format()` method: it should get a cologne log object and respond +to the `#format()` method: it should receive a cologne log object and respond with a string. ```javascript -new Cologne.Logger.Console({ - formatter : new Cologne.Formatter.Token({ +new Loggers.Console({ + formatter : new Formatters.Token({ formatString: '[{{_timestamp}}]{{_from}}: {{message}}' }) }); ``` -### Cologne.Logger.File +### Loggers.File This logger opens a writable stream to a file, to which it will append everything. Like the Console logger it supports a `formatter` property that will respond to the `#format()` method. -It MUST include a `file` property on initialization, otherwise it won't -know where to write and you'll get an exception and be sad. +It MUST include a `file` property on initialization, otherwise it will throw +an exception. ```javascript -new Cologne.Logger.File({ +new Loggers.File({ file: '/var/log/server_log.log', - formatter : new Cologne.Formatter.Token({ - formatString: '[{{_timestamp}}]{{_from}}: {{message}}' + formatter : new Formatters.Token({ + formatString: '[{{_ansi:_level}}{{_timestamp}}{{_ansi:reset}}]{{_from}}: {{message}}' }) }); ``` @@ -106,24 +99,23 @@ new Cologne.Logger.File({ We're working on a socket logger. It's separate so you don't have to install the socket dependencies if you don't want to. -If you need to, you can roll your own. Check info on the interfaces -below. - 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()` is a valid logger: ```javascript // A valid, very minimalistic logger -let simpleLogger = { - log : function () { - for (let logObject of arguments) { - this._doSomeMagic(logObject); +const simpleLogger = { + log: function(...logs) { + + for (const log of logs) { + this._doSomeMagic(logs); } }, - _doSomeMagic : function (logObject) { - console.log(logObject + "... but magical!"); + _doSomeMagic: function(log) { + + console.log(log + "... but magical!"); } }; @@ -134,20 +126,20 @@ logger.addLogger(simpleLogger); ## Formatters Cologne doesn't need formatters to work, and in fact they're optional in -the included workers. But if you would like to make your logs prettier, +the included loggers. But if you would like to make your logs prettier, then you can use one of the included formatters or roll your own. Formatters are objects that respond to the `#format()` method. It will receive a single cologne log object (see fields it includes below), and -it should return a string. That's all there is to it. +it should return a string. We include some formatters so you can get running real quicklike: -* `Cologne.Formatter.Simple` a simple predefined formatter -* `Cologne.Formatter.Token` a formatter that lets you define format +* `Formatters.Simple` a simple predefined formatter +* `Formatters.Token` a formatter that lets you define format strings that it will use to build your final log. -### Cologne.Formatter.Simple +### Formatters.Simple This is the lazy formatter, it just outputs the string in the following format: @@ -163,13 +155,14 @@ Where `_timestamp` is converted to ISO. * `colorize` : whether or not to add color. False by default. By default we don't colorize the output, but if you enable the flag this -formatter will add a bit of color in the level string. Red for bad, -yellow for warn, blue for info, and white for everything else. +formatter will add a bit of color in the level string. Red for error, crit, +alert, and emerg; yellow for warn; blue for info; green for debug; and white +for everything else. #### Usage ```javascript -new Cologne.Formatter.Simple({ +new Formatters.Simple({ colorize: true }); ``` @@ -181,7 +174,7 @@ co.log("hello world"); // -> [2016-01-21T05:50:36.505Z][INFO] Server Logger: hello world ``` -### Cologne.Formatter.Token +### Formatters.Token The token formatter lets you build strings with simple tokens. When instantiating, you can specify a `formatString` to interpolate @@ -200,7 +193,7 @@ you don't like it, you can specify your own. #### Usage ```javascript -new Cologne.Formatter.Token({ +new Formatters.Token({ formatString: '[{{_timestamp}}]{{_from}}: {{message}}' }); ``` @@ -237,36 +230,35 @@ returns a string. Here's an example of a logger that surrounds a log with sparkles: ```javascript -var simpleFormatter = { - format : function (logObject) { - return '✨' + logObject.message + '✨'; +const sparkleFormatter = { + format: function(logObject) { + + return `✨${logObject.message}✨`; } } -logger.addLogger(new Cologne.Logger.Console({ - formatter: simpleFormatter +logger.addLogger(new Loggers.Console({ + formatter: sparkleFormatter })); ``` ## The Cologne Log Format The cologne log format is a JSON based log format, based on the cobalt -log format, which is inturn based on Graylog's GELF. However, where GELF +log format, which is in turn based on Graylog's GELF. However, where GELF treats all internal fields without a prefix, and all user fields with a -prefix we do it backwards so it's easier to extend the object with -metadata from existing objects. Besides, we'll probably write the -default keys automatically so you shouldn't have to do that extra work. +prefix, we do it backwards so it's easier to extend the object with +metadata from existing objects. You could try to build it on your own, but you can use `#buildLog()` to build it without logging. ### Fields -* **\_timestamp** : A timestamp in miliseconds with fractions of a second - in the floating point area. +* **\_timestamp** : A bigint timestamp in nanoseconds * **\_cologneLog** : This is how we know if the log is already formatted and ready to go. This field is a string containing the - version of cologne log format it's using. It's `1.0.0` right now. + version of cologne log format it's using. It's `2.0.0` right now. * **\_from**: The sender of the log (Defaults to Generic Cologne Logger) * **\_level**: The level of the log (Defaults to 6) * **\_levelString**: The string corresponding to the log level (e.g. 7 -> @@ -295,6 +287,3 @@ only reports error or worse.) * Improve the API for buildLog * More loggers & formatters (will not be distributed in core cologne) * Improve tests - -[dependencies-shield]: https://david-dm.org/rbdr/cologne.svg -[circle-ci-shield]: https://circleci.com/gh/rbdr/cologne.svg?style=shield