From: Ruben Beltran del Rio Date: Sun, 20 Sep 2020 23:07:52 +0000 (+0200) Subject: Update docs and tooling X-Git-Url: https://git.r.bdr.sh/rbdr/cologne/commitdiff_plain/8b25c58124f87421fd3da836b884f338f33a8113 Update docs and tooling --- diff --git a/.eslintrc b/.eslintrc index bb7120d..2b34ba8 100644 --- a/.eslintrc +++ b/.eslintrc @@ -1,41 +1,19 @@ { + "parserOptions": { + "ecmaVersion": 2021 + }, + "extends": [ + "@hapi/eslint-config-hapi" + ], "rules": { "indent": [ 2, 2 ], - "quotes": [ - 2, - "single" - ], - "linebreak-style": [ - 2, - "unix" - ], - "semi": [ - 2, - "always" - ], - "no-trailing-spaces": [ - 2, - { - "skipBlankLines": false - } - ], - "eqeqeq": [ - 2, - "allow-null" - ], - "consistent-return": 2, - "curly": 2, - "dot-location": [2, "property"], - "guard-for-in": 2, - "no-extra-bind": 2 - }, - "env": { - "es6": true, - "node": true, - "browser": true + "no-undef": 2, + "require-yield": 0 }, - "extends": "eslint:recommended" + "ignorePatterns": [ + "tap-snapshots" + ] } diff --git a/.gitignore b/.gitignore index c1e0daf..3bbc2f1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,21 +1,6 @@ ## MAC OS .DS_Store -## TEXTMATE -*.tmproj -tmtags - -## EMACS -*~ -\#* -.\#* - -## VIM -*.swp - -## PROJECT::GENERAL -coverage -rdoc -pkg - ## PROJECT::SPECIFIC +.nyc_output +node_modules diff --git a/CHANGELOG b/CHANGELOG deleted file mode 100644 index 915f2e3..0000000 --- a/CHANGELOG +++ /dev/null @@ -1,24 +0,0 @@ -2016-01-22 Ruben Beltran Del Rio - - Version 1.1.0 - - * lib/cologne.js (buildLog): Add a new parameter called meta that expects an - object, it will be used to extend the log. - - * lib/cologne/log_utilities.js: Add the getLevelAnsi method that will - return an ANSI keyword depending on the log level sent. - - * lib/cologne/formatter/simple (format): Now uses getLevelAnsi, this means - that info and debug get colors (they used to be defualt.) info is blue, - debug is green. - - * lib/cologne/formatter/token (format): Adds support for the {{_ansi:_level}} - token that uses getLevelAnsi to generate color depending on the level. - - * README.md: Adds references to all new features - -2016-01-21 Ruben Beltran Del Rio - - Version 1.0.0 - - * all: initial release. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b1e8999 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,40 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [2.0.0] - 2020-09-20 +### Changed +- CHANGELOG format is now using `Keep a Changelog` format. +- CI updated to use `gitlab` instead of `circle` +- Updates dev dependencies +- Replaces `microtime` in favor of `process.hrtime.bigint()`. This means that + the timestamp is now in *nanoseconds* and has no decimal component. +- If you log an object, it will first attempt to read a `message` property. + All other properties will be extended with the log object. +- Renamed `log_utilities` to utilities +- Changes export so it uses a single object instead of having everything under + Cologne +- Update README to reflect current usage. + +### Removed +- Removes the meta parameter from buildLog. + +## [1.1.0] - 2016-01-22 +### Added +- a new parameter called meta that expects an object, it will be used to extend + the log +- gettLevelAnsi method, it returns an ANSI keyword depending on the log level + sent. +- Simple formatter uses `getLevelAnsi`, this means that info and debug get + colors: info is blue, debug is green. +- Token formatter now supports the `{{_ansi: _level}}` token that uses + `getLevelAnsi` to generatte color depending on the level. + +### Changed +- README.md now has references to all the new features + +## 1.0.0 - 2016-01-21 +### Added +- Initial log functionality 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 diff --git a/config/jsdoc.json b/config/jsdoc.json deleted file mode 100644 index 1ad13c4..0000000 --- a/config/jsdoc.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "plugins": ["plugins/markdown"], - "opts": { - "destination": "doc", - "readme": "README.md", - "template": "node_modules/jsdoc-augmented-template", - "recurse": true - } -} diff --git a/doc/COVERAGE.md b/doc/COVERAGE.md new file mode 100644 index 0000000..8127492 --- /dev/null +++ b/doc/COVERAGE.md @@ -0,0 +1,272 @@ +# TOC + - [test/cologne.js](#testcolognejs) + - [test/utilities.js](#testutilitiesjs) + - [test/formatters/simple.js](#testformatterssimplejs) + - [test/formatters/token.js](#testformatterstokenjs) + - [test/loggers/file.js](#testloggersfilejs) + - [test/loggers/console.js](#testloggersconsolejs) + + + +# test/cologne.js +#log() should send every argument to the loggers. + + +#log() should send the same arguments to all the loggers. + + +#log() should send all objects in cologne log format. + + +#log() should default to level 6. + + +#debug() should set to level 7. + + +#info() should set to level 6. + + +#notice() should set to level 5. + + +#warn() should set to level 4. + + +#error() should set to level 3. + + +#buildLog() should return a cologne log. + + +#buildLog() should default to level 6. + + +#buildLog() should use the specified level. + + +#buildLog() should use the message property as the message if available. + + +#buildLog() should extend the object with its properties. + + +#log() calls using a pre-built cologne log should maintain the log level. + + +#removeLogger() should do nothing if it can't find a logger. + + +#removeLogger() should remove a logger. + + +#removeLogger() should no longer affect removed logs. + + +#addLogger() should add loggers after instance is live. + + + +ok - test/cologne.js + +# test/utilities.js +::now() should give a precise bigint timestamp. + + +::stringify() should behave like JSON.stringify for non-circular objects. + + +::stringify() should replace circular references with a string. + + +::stringify() should convert bigint to string. + + +::getAnsiCode is sending the correct reset code. + + +::getAnsiCode() should give us a reset code if something weird is sent. + + +::getAnsiCode() should not have duplicated non-reset codes. + + +::getAnsiCode() should not return a reset code in any other supported code. + + +::gettLevelAnsi is red for emerg. + + +::gettLevelAnsi is red for alert. + + +::gettLevelAnsi is red for crit. + + +::gettLevelAnsi is red for error. + + +::gettLevelAnsi is yellow for warn. + + +::gettLevelAnsi is blue for notice. + + +::gettLevelAnsi is blue for info. + + +::gettLevelAnsi is green for debug. + + +::gettLevelAnsi is default for other values. + + + +ok - test/utilities.js + +# test/formatters/simple.js +#format() should output a string in plain mode. + + +#format() should include the from property in plain mode. + + +#format() should include the timestamp property in iso format in plain mode. + + +#format() should include the level string property in plain mode. + + +#format() should include the message property in plain mode. + + +#format() should output a string in color mode. + + +#format() should include the from property in color mode. + + +#format() should include the timestamp property in iso format in color mode. + + +#format() should include the level string property in color mode. + + +#format() should include the message property in color mode. + + +#format() should colorize the string. + + +#format() should colorize only a bit of the string. + + + +ok - test/formatters/simple.js + +# test/formatters/token.js +#format() should output a string in default mode. + + +#format() should include the message in default mode. + + +#format() should output a string in custom mode. + + +#format() with custom string should include the specified tokens (check 1). + + +#format() with custom string should include the specified tokens (check 2). + + +#format() with iso date should include the timestamp as an iso date. + + +#format() should not replace tokens that don't match. + + +#format() should output a string in ansi mode. + + +#format() with ansi tokens should colorize the string. + + +#format() with ansi reset should reset the string. + + +#format() with ansi tokens should colorize the string based on level. + + +#format() should output a string in plain date mode. + + +#format() with plain date should include the timestamp as-is. + + +#format() should output a string in custom search mode. + + +#format() with a custom search, should properly match the new tokens. + + + +ok - test/formatters/token.js + +# test/loggers/file.js +raw file. + + +formatted file. + + +it should send all params to the file. + + +it should log the raw json object. + + +it should send all params to the file. + + +it should log the formatted object. + + + +ok - test/loggers/file.js + +# test/loggers/console.js +It should default to the global console. + + +It should send debug messages to console's #log. + + +It should send info and notice messages to console's #info. + + +It should send warn messages to console's #warn. + + +It should send error messages to console's #error. + + +If available, it should send the objects to the formatter. + + + +ok - test/loggers/console.js +----------------|----------|----------|----------|----------|-------------------| +File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s | +----------------|----------|----------|----------|----------|-------------------| +All files | 100 | 100 | 100 | 100 | | + lib | 100 | 100 | 100 | 100 | | + cologne.js | 100 | 100 | 100 | 100 | | + utilities.js | 100 | 100 | 100 | 100 | | + lib/formatters | 100 | 100 | 100 | 100 | | + simple.js | 100 | 100 | 100 | 100 | | + token.js | 100 | 100 | 100 | 100 | | + lib/loggers | 100 | 100 | 100 | 100 | | + console.js | 100 | 100 | 100 | 100 | | + file.js | 100 | 100 | 100 | 100 | | +----------------|----------|----------|----------|----------|-------------------| diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..d96cffb --- /dev/null +++ b/doc/README.md @@ -0,0 +1,476 @@ +## Classes + +
+
Cologne
+
+
Utilities
+
+
+ +## Objects + +
+
Formatters : object
+

Namespace that includes the built-in formatters.

+
+
Loggers : object
+

Namespace that includes the built-in loggers.

+
+
+ +## Typedefs + +
+
tCologneLog : object
+

The main cologne log format.

+
+
+ +## Interfaces + +
+
ILogger
+

Main interface for Cologne Loggers

+
+
IFormatter
+

Main interface for Cologne Formatters

+
+
+ + + +## ILogger +Main interface for Cologne Loggers + +**Kind**: global interface + + +### ILogger.log() +Receives any number of cologne log objects and logs them. + +**Kind**: static method of [ILogger](#ILogger) + + +## IFormatter +Main interface for Cologne Formatters + +**Kind**: global interface + + +### IFormatter.format(logObject) ⇒ string +Receives a cologne log object and returns a formatted string. + +**Kind**: static method of [IFormatter](#IFormatter) +**Returns**: string - the formatted log + +| Param | Type | Description | +| --- | --- | --- | +| logObject | [tCologneLog](#tCologneLog) | the log to be formatted | + + + +## Cologne +**Kind**: global class + +* [Cologne](#Cologne) + * [new Cologne()](#new_Cologne_new) + * [.from](#Cologne+from) : String + * [.loggers](#Cologne+loggers) : [Array.<ILogger>](#ILogger) + * [.addLogger(logger)](#Cologne+addLogger) + * [.removeLogger(logger)](#Cologne+removeLogger) ⇒ [Array.<ILogger>](#ILogger) + * [.buildLog(message, [level])](#Cologne+buildLog) ⇒ [tCologneLog](#tCologneLog) + * [.log()](#Cologne+log) + * [.debug()](#Cologne+debug) + * [.info()](#Cologne+info) + * [.notice()](#Cologne+notice) + * [.warn()](#Cologne+warn) + * [.error()](#Cologne+error) + + + +### new Cologne() +The main logger class. It can be instantiated with loggers in order to +send messages to different destinations. + + + +### cologne.from : String +The name of this logger, useful to distinguish between different +loggers. + +**Kind**: instance property of [Cologne](#Cologne) +**Default**: 'Generic Cologne Logger + + +### cologne.loggers : [Array.<ILogger>](#ILogger) +The array containing all the loggers it will call to. + +**Kind**: instance property of [Cologne](#Cologne) +**Default**: [] + + +### cologne.addLogger(logger) +Adds a logger to the current instance. + +**Kind**: instance method of [Cologne](#Cologne) + +| Param | Type | Description | +| --- | --- | --- | +| logger | [ILogger](#ILogger) | the logger to add | + + + +### cologne.removeLogger(logger) ⇒ [Array.<ILogger>](#ILogger) +Removes a logger from the current instance. + +**Kind**: instance method of [Cologne](#Cologne) +**Returns**: [Array.<ILogger>](#ILogger) - the removed log, inside an array. + +| Param | Type | Description | +| --- | --- | --- | +| logger | [ILogger](#ILogger) | the logger to remove | + + + +### cologne.buildLog(message, [level]) ⇒ [tCologneLog](#tCologneLog) +Given a message, it builds a cologne log object without logging it. +If you send a cologne log object, it will only update the level. + +If the message is an object, the log object will be extended with +its properties. + +**Kind**: instance method of [Cologne](#Cologne) +**Returns**: [tCologneLog](#tCologneLog) - a cologne log object + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| message | \* | | The message to log | +| [level] | number | 6 | The level of the message to log | + + + +### cologne.log() +Default log function. Sends arguments to loggers. If not specified in log +object, it will set the severity to 6 - INFO. + +**Kind**: instance method of [Cologne](#Cologne) + + +### cologne.debug() +Logs with debug level + +**Kind**: instance method of [Cologne](#Cologne) + + +### cologne.info() +Logs with info level + +**Kind**: instance method of [Cologne](#Cologne) + + +### cologne.notice() +Logs with notice level + +**Kind**: instance method of [Cologne](#Cologne) + + +### cologne.warn() +Logs with warn level + +**Kind**: instance method of [Cologne](#Cologne) + + +### cologne.error() +Logs with error level + +**Kind**: instance method of [Cologne](#Cologne) + + +## Utilities +**Kind**: global class + +* [Utilities](#Utilities) + * [new Utilities()](#new_Utilities_new) + * [.now()](#Utilities.now) ⇒ bigint + * [.stringify(object)](#Utilities.stringify) ⇒ String + * [.getAnsiCode(ansiString)](#Utilities.getAnsiCode) ⇒ String + * [.getLevelAnsi(level)](#Utilities.getLevelAnsi) ⇒ String + + + +### new Utilities() +Container object for utilities used by loggers. + + + +### Utilities.now() ⇒ bigint +Returns the current timestamp in nanoseconds as a bigint. + +**Kind**: static method of [Utilities](#Utilities) +**Returns**: bigint - current time in nanoseconds, including fractions. + + +### Utilities.stringify(object) ⇒ String +Stringifies objects, avoiding circular references. + +**Kind**: static method of [Utilities](#Utilities) +**Returns**: String - the stringified object + +| Param | Type | Description | +| --- | --- | --- | +| object | Object | the object to stringify | + + + +### Utilities.getAnsiCode(ansiString) ⇒ String +Given an ansi keyword, it will return the appropriate code. + +**Kind**: static method of [Utilities](#Utilities) +**Returns**: String - the ansi code + +| Param | Type | Description | +| --- | --- | --- | +| ansiString | String | the name of the desired code | + + + +### Utilities.getLevelAnsi(level) ⇒ String +Given a level, it will return the appropriate ansi keyword related +to it. + +**Kind**: static method of [Utilities](#Utilities) +**Returns**: String - the ansi keyword + +| Param | Type | Description | +| --- | --- | --- | +| level | number | the level of the log | + + + +## Formatters : object +Namespace that includes the built-in formatters. + +**Kind**: global namespace + +* [Formatters](#Formatters) : object + * [.Simple](#Formatters.Simple) + * [new Simple()](#new_Formatters.Simple_new) + * [.colorize](#Formatters.Simple+colorize) : Boolean + * [.format(logObjet)](#Formatters.Simple+format) ⇒ String + * [.Token](#Formatters.Token) + * [new Token()](#new_Formatters.Token_new) + * [.formatString](#Formatters.Token+formatString) : String + * [.replaceRule](#Formatters.Token+replaceRule) : RegExp + * [.isoDate](#Formatters.Token+isoDate) : Boolean + * [.format(log)](#Formatters.Token+format) ⇒ String + + + +### Formatters.Simple +**Kind**: static class of [Formatters](#Formatters) +**Implements**: [IFormatter](#IFormatter) + +* [.Simple](#Formatters.Simple) + * [new Simple()](#new_Formatters.Simple_new) + * [.colorize](#Formatters.Simple+colorize) : Boolean + * [.format(logObjet)](#Formatters.Simple+format) ⇒ String + + + +#### new Simple() +Simple formatter. Outputs a predefined format: +`[{{_timestamp}}][{{_levelString}}] {{_from}}: {{message}}`; + + + +#### simple.colorize : Boolean +Flag that tells us whether or not to use ANSI color. Defaults to +false. + +**Kind**: instance property of [Simple](#Formatters.Simple) +**Default**: false + + +#### simple.format(logObjet) ⇒ String +Main entry point, it will read the incoming log object and convert +it to the output string. + +**Kind**: instance method of [Simple](#Formatters.Simple) +**Returns**: String - the formatted object + +| Param | Type | Description | +| --- | --- | --- | +| logObjet | [tCologneLog](#tCologneLog) | the log to format | + + + +### Formatters.Token +**Kind**: static class of [Formatters](#Formatters) +**Implements**: [IFormatter](#IFormatter) + +* [.Token](#Formatters.Token) + * [new Token()](#new_Formatters.Token_new) + * [.formatString](#Formatters.Token+formatString) : String + * [.replaceRule](#Formatters.Token+replaceRule) : RegExp + * [.isoDate](#Formatters.Token+isoDate) : Boolean + * [.format(log)](#Formatters.Token+format) ⇒ String + + + +#### new Token() +Token formatter. Given a format string it will attempt to output +a message. + + + +#### token.formatString : String +The string to use as a template string. By default, any property +inside double curly braces `{{likeThis}}` will be extracted from +the object and replaced. If the object does not contain the +property, it will leave it. + +**Kind**: instance property of [Token](#Formatters.Token) +**Default**: '{{message}}' + + +#### token.replaceRule : RegExp +The regex rule to use to match the tokens. + +**Kind**: instance property of [Token](#Formatters.Token) +**Default**: /{{(.*)}}/g + + +#### token.isoDate : Boolean +Flag that specifies whether or not to use an isoDate when using +`_timestamp`. If false it will output the raw timestamp. + +**Kind**: instance property of [Token](#Formatters.Token) +**Default**: true + + +#### token.format(log) ⇒ String +Main entry point, it will read the incoming log object and convert +all the tokens to their corresponding representation, finally +returning the string. + +**Kind**: instance method of [Token](#Formatters.Token) +**Returns**: String - the formatted object + +| Param | Type | Description | +| --- | --- | --- | +| log | [tCologneLog](#tCologneLog) | the log to format | + + + +## Loggers : object +Namespace that includes the built-in loggers. + +**Kind**: global namespace + +* [Loggers](#Loggers) : object + * [.Console](#Loggers.Console) + * [new Console()](#new_Loggers.Console_new) + * [.console](#Loggers.Console+console) : Object + * [.formatter](#Loggers.Console+formatter) : [IFormatter](#IFormatter) + * [.log()](#Loggers.Console+log) ⇒ undefined + * [.File](#Loggers.File) + * [new File()](#new_Loggers.File_new) + * [.file](#Loggers.File+file) : string + * [.formatter](#Loggers.File+formatter) : [IFormatter](#IFormatter) + * [.log()](#Loggers.File+log) ⇒ undefined + + + +### Loggers.Console +**Kind**: static class of [Loggers](#Loggers) +**Implements**: [ILogger](#ILogger) + +* [.Console](#Loggers.Console) + * [new Console()](#new_Loggers.Console_new) + * [.console](#Loggers.Console+console) : Object + * [.formatter](#Loggers.Console+formatter) : [IFormatter](#IFormatter) + * [.log()](#Loggers.Console+log) ⇒ undefined + + + +#### new Console() +Logger for the javascript console. + + + +#### console.console : Object +The console it will write to, can be any object that looks +and acts like a console, including other cologne objects. + +**Kind**: instance property of [Console](#Loggers.Console) +**Default**: global.console + + +#### console.formatter : [IFormatter](#IFormatter) +The formatter it will use to output the log. If not present it +will output raw JSON + +**Kind**: instance property of [Console](#Loggers.Console) +**Default**: null + + +#### console.log() ⇒ undefined +Main entry point, for each incoming argument it will attempt to +format and send to the console. + +**Kind**: instance method of [Console](#Loggers.Console) + + +### Loggers.File +**Kind**: static class of [Loggers](#Loggers) +**Implements**: [ILogger](#ILogger) + +* [.File](#Loggers.File) + * [new File()](#new_Loggers.File_new) + * [.file](#Loggers.File+file) : string + * [.formatter](#Loggers.File+formatter) : [IFormatter](#IFormatter) + * [.log()](#Loggers.File+log) ⇒ undefined + + + +#### new File() +Logger for files. + + + +#### file.file : string +Path to the file it will write to, must be readable. + +**Kind**: instance property of [File](#Loggers.File) +**Default**: "null" + + +#### file.formatter : [IFormatter](#IFormatter) +The formatter it will use to output the log. If not present it +will output raw JSON + +**Kind**: instance property of [File](#Loggers.File) +**Default**: null + + +#### file.log() ⇒ undefined +Main entry point, for each incoming argument it will attempt to +format and send to the stream to be written. + +**Kind**: instance method of [File](#Loggers.File) + + +## tCologneLog : object +The main cologne log format. + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| _timestamp | Bigint | the timestamp in nanoseconds | +| _cologneLog | String | main identifier, encodes the version of the cologne log format being used. | +| _from | String | the origin of the log message. | +| _level | String | the severity level of the log, uses syslog priorities. | +| _levelString | String | the severity level keyword of the log, uses syslog priority keywords. | + diff --git a/lib/loggers/console.js b/lib/loggers/console.js index 116b04b..5e5ded1 100644 --- a/lib/loggers/console.js +++ b/lib/loggers/console.js @@ -6,6 +6,7 @@ const Utilities = require('../utilities'); * Logger for the javascript console. * * @implements ILogger + * @memberof Loggers * @class Console */ module.exports = class ConsoleLogger {