lokua.net.logger

Highly configurable, styled and level-based logging for modern browsers.

For a node version with almost identical API, see lokua.net.node-logger

Install

npm install lokua.net.logger

Usage

<script src='node_modules/lokua.net.logger/dist/logger.min.js'></script>
<script>
  const logger = new Logger('MAIN', /*,  options */)
  logger.info('...')
</script>

If you are using an ES6 module bundler you can import directly from the src:

import Logger from 'path-to/node_modules/lokua.net.logger/src/logger'

Note: Logger has been primarily developed for use in latest Chrome Version 42.0.2311.90 and secondarily for Firefox 36.0.4. There are currently some kinks regarding Firefox which may solved in version 40. See this issue on bugzilla

API

Logger(name, [level|options])

Overview

lokua.net.logger is a UMD module, exporting a single global Logger class. The Logger constructor takes a required name and optional level, or options hash. Currently Logger supports the following wrapped console methods (check out mdn:console for basic console usage):

• log
• trace
• debug (via log)
• info
• warn
• error
• group
• groupEnd

A Logger instance will only log calls that are greater or equal to its current level. For example if an instance is set to level 5, only errors will be logged. This level is per logger, so Logger A's level will not effect Logger B. There is a global off switch available through the static Logger.off, which will silence all loggers regardless of their level.

The order of the levels are as follows:

• 0 (aka Logger.LOG) : log
• 1 (aka Logger.TRACE) : trace
• 2 (aka Logger.DEBUG) : debug
• 3 (aka Logger.INFO) : info
• 4 (aka Logger.WARN) : warn
• 5 (aka Logger.ERROR) : error

Customization

Every log message is prefixed according to Logger#options.format array, which sets both the ordering of formats and whether to include them. The default format is ['name', 'level', 'date', 'source']. Each of these formats can be custom styled with CSS string via Logger#options.<name|level|date|source>Style.

Example

const logger = new Logger('MAIN', {

  // only log warnings and errors
  level: Logger.WARN,

  // custom format order excluding `name` and `source`
  format: ['date', 'level']

  dateStyle: 'color:lightblue;font-style:italic',
})

See: Logger._defaultOptions

Params:

• name {String}the name of this Logger instance

• [level|options] {Object|Number}Either a hash with configuration options, or a number setting this instance's logging level.

Logger#level

Convenience getter/setter for Logger#options.level

Logger#setOptions([options])

Set multiple options at once. If called with no arguments, null, or an empty object, #setOptions will restore the default options

See: Logger._defaults

Params:

• [options] {Object}

Return:

• {Logger} this

Logger#group()

console#group wrapper

Return:

• {Logger} this

Logger#groupEnd()

console#groupEnd wrapper

Return:

• {Logger} this

Logger#log()

console#log wrapper

Return:

• {Logger} this

Logger#trace()

console#trace wrapper

Return:

• {Logger} this

Logger#debug()

console#log wrapper

Return:

• {Logger} this

Logger#info()

console#info wrapper

Return:

• {Logger} this

Logger#warn()

console#warn wrapper

Return:

• {Logger} this

Logger#error()

console#error wrapper

Return:

• {Logger} this

Logger.getLogger(name)

Get a Logger instance by name

Params:

• name {String}The name as passed to the Logger constructor

Return:

• {Logger} the logger instance or undefined if no match

Logger.setDefaults(defaults)

Override the factory defaults for all Loggers. New defaults object will be merged with existing. Note that these defaults can not be restored

See: Logger._defaults

Params:

• defaults {Object}

Logger.off

Disable logging for all Loggers

Logger._defaults

Default options for all Logger instances

Properties:

• level {Number}The logger's level. After instantiation, the level can be set directly via Logger#level

• format {Array}et the order of the log prefix. alid values include name, level, date, source.

• dateType {String}Set the output type of the date format. Valid values include iso, utc, and locale, which refer to their respective Date#to***String methods

• dateOutput {String}Set whether to include date, time, or datetime in the date format.

• dateFormatter {Function}Provide a custom date formatting function. The function will be called with a Date object. Note that providing a dateFormatter will cause the dateType and dateOutput options to be ignored, but it has no impact on the dateStyle option

• useAbsoluteSource {Boolean}If true, output the full absolute path to the sourcecode; otherwise, just the filename, line, and column

• levelStyle {String}CSS format string for the level output. Defaults to 'auto', which will output logical colors to levels (error=red, etc)

• messageStyle {String}CSS format string for the log's message

• sourceStyle {String}CSS format string for the log's source output

• nameStyle {String}CSS format string for the log's name output

• dateStyle {String}CSS format string the log's date output

• newLine {Boolean}If true, separates a log's prefix and message with a newline

• stackDepth {Number}In order to output source code line numbers, Logger internally generates a stack trace to find where the logger method was called. Since the Console api is unstable and varies between vendors and version, the exact location is not always the same; hence, stackdepth. Use this only if Logger is reporting incorrect line outputs.

Logger.LOG

Level alias

Logger.TRACE

Level alias

Logger.DEBUG

Level alias

Logger.INFO

Level alias

Logger.WARN

Level alias

Logger.ERROR

Level alias

_colors

Colors used when #options.levelStyle===auto

License

The MIT License (MIT) Copyright (c) 2015, 2016 Joshua Jay Kleckner

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.