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
If you are using an ES6 module bundler you can import directly from the src:
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
(vialog
)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 = 'MAIN' // only log warnings and errors level: LoggerWARN // 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 includename
,level
,date
,source
. -
dateType {String}
Set the output type of thedate
format. Valid values includeiso
,utc
, andlocale
, which refer to their respectiveDate#to***String
methods -
dateOutput {String}
Set whether to includedate
,time
, ordatetime
in thedate
format. -
dateFormatter {Function}
Provide a custom date formatting function. The function will be called with aDate
object. Note that providing a dateFormatter will cause thedateType
anddateOutput
options to be ignored, but it has no impact on thedateStyle
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.