loglevel

Don't debug with logs alone - check out HTTP Toolkit: beautiful, powerful & open-source tools for building, testing & debugging HTTP(S)

Minimal lightweight simple logging for JavaScript (browsers, node.js or elsewhere). loglevel extends console.log() & friends with level-based logging and filtering, with none of console's downsides.

Test it out live in your browser console at https://pimterry.github.io/loglevel/demo/index.html

Loglevel is a barebones reliable everyday logging library. It does not do fancy things, it does not let you reconfigure appenders or add complex log filtering rules or boil tea (more's the pity), but it does have the all core functionality that you actually use:

Features

Simple

Log things at a given level (trace/debug/info/warn/error) to the console object (as seen in all modern browsers & node.js).
Filter logging by level (all the above or 'silent'), so you can disable all but error logging in production, and then run log.setLevel("trace") in your console to turn it all back on for a furious debugging session.
Single file, no dependencies, weighs in at 1.4 KB minified and gzipped.

Effective

Log methods gracefully fall back to simpler console logging methods if more specific ones aren't available: so calls to log.debug() go to console.debug() if possible, or console.log() if not.
Logging calls still succeed even if there's no console object at all, so your site doesn't break when people visit with old browsers that don't support the console object (here's looking at you, IE) and similar.
This then comes together giving a consistent reliable API that works in every JavaScript environment with a console available, and never breaks anything anywhere else.

Convenient

Log output keeps line numbers: most JS logging frameworks call console.log methods through wrapper functions, clobbering your stacktrace and making the extra info many browsers provide useless. We'll have none of that thanks.
It works with all the standard JavaScript loading systems out of the box (CommonJS, AMD, or just as a global).
Logging is filtered to "warn" level by default, to keep your live site clean in normal usage (or you can trivially re-enable everything with an initial log.enableAll() call).
Magically handles situations where console logging is not initially available (IE8/9), and automatically enables logging as soon as it does become available (when developer console is opened).
TypeScript type definitions included, so no need for extra @types packages.
Extensible, to add other log redirection, filtering, or formatting functionality, while keeping all the above (except you will clobber your stacktrace, see “Plugins” below).

Downloading loglevel

If you're using NPM, you can just run npm install loglevel.

Alternatively, loglevel is also available via Bower (bower install loglevel), as a Webjar, or an Atmosphere package (for Meteor)

Alternatively if you just want to grab the file yourself, you can download either the current stable production version or the development version directly, or reference it remotely on unpkg at https://unpkg.com/loglevel/dist/loglevel.min.js (this will redirect to a latest version, use the resulting redirected URL if you want to pin that version).

Finally, if you want to tweak loglevel to your own needs or you immediately need the cutting-edge version, clone this repo and see Developing & Contributing below for build instructions.

Setting it up

loglevel supports AMD (e.g. RequireJS), CommonJS (e.g. Node.js) and direct usage (e.g. loading globally with a <script> tag) loading methods. You should be able to do nearly anything, and then skip to the next section anyway and have it work. Just in case, though, here's some specific examples that definitely do the right thing:

CommonsJS (e.g. Node)

var log = require('loglevel');
log.warn("unreasonably simple");

AMD (e.g. RequireJS)

define(['loglevel'], function(log) {
   log.warn("dangerously convenient");
});

Directly in your web page

<script src="loglevel.min.js"></script>
<script>
log.warn("too easy");
</script>

As an ES6 module

loglevel is written as a UMD module, with a single object exported. Unfortunately, ES6 module loaders & transpilers don't all handle this the same way. Some will treat the object as the default export, while others use it as the root exported object. In addition, loglevel includes a default property on the root object, designed to help handle this difference. Nonetheless, there are two possible syntaxes that might work for you:

For most tools, using the default import is the most convenient and flexible option:

import log from 'loglevel';
log.warn("module-tastic");

For some tools though, it might better to wildcard import the whole object:

import * as log from 'loglevel';
log.warn("module-tastic");

There's no major difference, unless you're using TypeScript & building a loglevel plugin (in that case, see https://github.com/pimterry/loglevel/issues/149). In general though, just use whichever suits your environment, and everything should work out fine.

With noConflict()

If you're using another JavaScript library that exposes a log global, you can run into conflicts with loglevel. Similarly to jQuery, you can solve this by putting loglevel into no-conflict mode immediately after it is loaded onto the page. This resets the log global to its value before loglevel was loaded (typically undefined), and returns the loglevel object, which you can then bind to another name yourself.

For example:

<script src="loglevel.min.js"></script>
<script>
var logging = log.noConflict();

logging.warn("still pretty easy");
</script>

TypeScript

loglevel includes its own type definitions, assuming you're using a modern module environment (e.g. Node.JS, webpack, etc), you should be able to use the ES6 syntax above, and everything will work immediately. If not, file a bug!

If you really want to use LogLevel as a global however, but from TypeScript, you'll need to declare it as such first. To do that:

Create a loglevel.d.ts file
Ensure that file is included in your build (e.g. add it to include in your tsconfig, pass it on the command line, or use ///<reference path="./loglevel.d.ts" />)

In that file, add:

import * as log from 'loglevel';
export as namespace log;
export = log;

Documentation

Methods

The loglevel API is extremely minimal. All methods are available on the root loglevel object, which we suggest you name log (this is the default if you import it globally, and is what's set up in the above examples). The API consists of:

Logging Methods

5 actual logging methods, ordered and available as:

log.trace(msg)
log.debug(msg)
log.info(msg)
log.warn(msg)
log.error(msg)

log.log(msg) is also available, as an alias for log.debug(msg), to improve compatibility with console, and make migration easier.

Exact output formatting of these will depend on the console available in the current context of your application. For example, many environments will include a full stack trace with all trace() calls, and icons or similar to highlight other calls.

These methods should never fail in any environment, even if no console object is currently available, and should always fall back to an available log method even if the specific method called (e.g. warn) isn't available.

Be aware that this means that these methods won't always produce exactly the output you expect in every environment; loglevel only guarantees that these methods will never explode on you, and that it will call the most relevant method it can find, with your argument. For example, log.trace(msg) in Firefox before version 64 prints the stacktrace by itself, and doesn't include your message (see #84).

`log.setLevel(level, [persist])`

This disables all logging below the given level, so that after a log.setLevel("warn") call log.warn("something") or log.error("something") will output messages, but log.info("something") will not.

This can take either a log level name or 'silent' (which disables everything) in one of a few forms:

As a log level from the internal levels list, e.g. log.levels.SILENT ← for type safety
As a string, like 'error' (case-insensitive) ← for a reasonable practical balance
As a numeric index from 0 (trace) to 5 (silent) ← deliciously terse, and more easily programmable (...although, why?)

Where possible, the log level will be persisted. LocalStorage will be used if available, falling back to cookies if not. If neither is available in the current environment (e.g. in Node), or if you pass false as the optional 'persist' second argument, persistence will be skipped.

If log.setLevel() is called when a console object is not available (in IE 8 or 9 before the developer tools have been opened, for example) logging will remain silent

Loglevel

Install / Use

README