dalogga
dalogga
is yet another Javascript logger. It supports different logging levels (trace, debug, log, info, warn, error, fatal), global enabling/disabling of all output, custom prefixes, automatic JSON serialisation and colours. It can run both in the browser and in Node, and can be imported using any of the main module systems (ES6 modules, CommonJS, AMD, global scope).
Usage
Use npm
to install the module:
npm install --save dalogga
Using with ES6 modules
Simply import the createLogger
function from the library:
import { createLogger } from 'dalogga';
const logger = createLogger();
logger.info('it works with ES6 modules!');
Using with CommonJS modules
Simply require the dalogga
package and call its createLogger
method:
var dalogga = require('dalogga');
var logger = dalogga.createLogger();
logger.info('it works with CommonJS!');
Using as a globally-scoped variable
For those frontend projects that do not use a module bundler (like webpack or browserify), it is possible to include a script
tag in the page, and the dalogga
library will be available in the global scope:
<script src="path/to/dalogga.js"></script>
<script>
var logger = dalogga.createLogger();
logger.info('it works in the global scope too!');
</script>
Initialisation settings
When calling the createLogger
function, it is possible to specify some initialisation settings to customise the logger. These settings are specified through an optional object, passed as the first argument of the createLogger
function. Example:
const logger = dalogga.createLogger({
logFunction: (...values) => { sendSomewhere(values); },
prefixes: [
'Static prefix',
(level, values) => 'Messages passed: ' + values.length,
'Another static prefix',
],
useColours: true,
level: 'debug',
isEnabled: false,
});
Parameters
The settings object supports the following parameters:
-
logFunction (function|object): the function that writes the messages. Defaults to the STDOUT and STDERR output through the console
object. Specify a single function to use for all log levels (e.g. logFunction: fn1
), or a mapping object for granular control. e.g.: logFunction: { debug: fn1, info: fn2, error: fn3 }
-
prefixes (array|object): an array of prefix values or functions that will be used to prepend the output with custom values. Can be also specified as a single value. See below for more information. Defaults to 'DATE [LEVEL] - '
-
useColours (boolean): use coloured text for better readability in a TTY environment. Use true or false to force the setting, leave null or undefined to autodetect the output, so that the colours will only be used when writing to a terminal environment. Defaults to autodetect.
-
level (number|string): the minimum level of logging that will produce an output. Use the level name (e.g. 'warn') or the level number. Defaults to 'trace' (write all levels). The level number goes from 0 to 6, and each value corresponds to the following:
- 0: trace
- 1: debug
- 2: log
- 3: info
- 4: warn
- 5: error
- 6: fatal
-
isEnabled (boolean): when this parameter is false
, the logger will not output any data. Defaults to true
.
Logger methods
The createLogger
function returns an object that exposes the following methods:
- disable(): once this method is invoked, the logger will not output any data at any level, until the
enable
method is called - enable(): if the logger was previously disabled, it will get re-enabled. The logger level will remain unaffected
- isEnabled(): returns a boolean value that tells whether the logger will generate any output when the logging methods are called
- getLevel(): returns the name of the current minimum level that generates an output
- setLevel(level): sets the current minimum level that generates an output. The
level
argument can be either the level name, or the corresponding level number (see list above)
In addition to the above 'maintenance' methods, the logger also exposes the actual methods to print the output. When one of these methods is invoked, the function prints all the prefixes followed by the specified values. These methods accept any number of arguments of any type. If any of those values is an object, it gets automatically serialised to JSON format. The list of methods is listed below:
- trace(values)
- debug(values)
- log(values)
- info(values)
- warn(values)
- error(values)
- fatal(values)
Colours
When printing to a terminal environment, dalogga supports printing coloured text. The following colours are supported:
- black
- red
- green
- yellow
- blue
- magenta
- cyan
- white
To print a line using a different colour than the default one, call the logging method in the following way: logger.level.colour(values)
.
Examples:
logger.info.blue('This is blue text');
logger.log.yellow('This is yellow text');
logger.error.red('This is a red error text');
When the coloured output is disabled (so when not running in TTY environment, or when setting the useColours
parameter to false
when creating the logger), the colour methods will have exactly the same output as the "normal" logging methods - e.g. calling logger.log.blue('foo')
will be the same as calling logger.log('foo')
.
Prefixes
By default, the logger will prefix every written line with the current timestamp, the specified logging level, and a hyphen separator. For example the command logger.warn('you have been warned!')
will output the following text:
2016-08-11T10:41:16.713Z [WARN] - you have been warned!
When running in a terminal environment, the timestamp prefix will use the cyan colour, while the log level prefix will have a different colour for each level.
It is possible to customise the prefixes to use, and to create custom ones. This can be done through the prefixes
parameter of the settings object passed to the createLogger
function. The parameter expects an array of prefixes (or an individual prefix, which is equivalent to an array with a single element). Setting the prefixes
parameter will override the default prefixes, so to disable all prefixes, simply pass an empty array:
const logger = dalogga.createLogger({
prefixes: [],
});
Specify static prefixes
To specify a static prefix (i.e. a value that will be the same in evey line of the output), simply add that value to the prefixes
array, e.g.:
const logger = dalogga.createLogger({
prefixes: [
'prefix1',
'prefix2'
],
});
Specify dynamic prefixes
It is also possible to compute the value of the prefixes just before printing the line, so that the output will contain information that is specific to every entry. The timestamp prefix is an example of this. To specify a dynamic prefix, add a function to the prefixes
array. This function will be executed every time a log line needs to be printed. The function will receive two arguments:
- levelName: the name of the level that was just invoked
- messages: the array of values (not including prefixes) that will be printed
The value that will be printed as the prefix is the value returned by the function.
Example:
const logger = dalogga.createLogger({
prefixes: [
(level, values) => 'Messages: ' + values.length,
'-',
],
});
logger.log('value1', 'value2');
Reusing the default prefixes
The dalogga
library also exposes the functions for the default prefixes (timestamp and level), so that they can be combined with any other custom prefixes. Example:
const logger = dalogga.createLogger({
prefixes: [
dalogga.prefixes.levelPrefix,
dalogga.prefixes.timestampPrefix,
'-',
],
});
When using ES6 modules, import the prefixes
exported property, which will contain the prefix functions. Example:
import { createLogger, prefixes } from 'dalogga';
const logger = createLogger({
prefixes: [
prefixes.timestampPrefix,
'-',
],
});