clay-loglevel

loglevel

Minimal lightweight simple logging for JavaScript. loglevel replaces console.log() and friends with level-based logging and filtering, with none of console's downsides.

This 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 <1KB 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)

Downloading loglevel

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

loglevel is also available via Bower (bower install loglevel), JamJS (jam install loglevel) or as a Webjar.

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 CDNJS at //cdnjs.cloudflare.com/ajax/libs/loglevel/0.6.0/loglevel.min.js

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.info("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.error("too easy");
</script> 

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 to '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.error("still pretty easy");
</script> 

Documentation

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

• 5 actual logging methods, ordered and available as:

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

  Exact output formatting of these will depend on the console available in the current context of your application. Notably, 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.

• A log.setLevel(level) method.

  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 (i.e. in Node) 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 until the console becomes available, and then begin logging at the requested level.

• log.enableAll() and log.disableAll() methods.

  These enable or disable all log messages, and are equivalent to log.setLevel("trace") and log.setLevel("silent") respectively.

• log.on(method, fn) and log.off(method, [fn]) methods.

  These create or remove event listeners for logging methods. WARNING: Calling these methods will cause logging to happen in a wrapped fashion.
  This will lead to gross logs in the console, but is necessary to intercept. e.g. log.on('error', function() { sendToServer(arguments) })

Developing & Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.

Builds can be run with grunt: run grunt dist to build a distributable version of the project (in /dist), or grunt test to just run the tests and linting. During development you can run grunt watch and it will monitor source files, and rerun the tests and linting as appropriate when they're changed.

Also, please don't manually edit files in the "dist" subdirectory as they are generated via Grunt. You'll find source code in the "lib" subdirectory!

Release process

To do a release of loglevel:

• Update the version number in package.json and bower.json
• Run grunt dist to build a distributable version in dist/
• Update the release history in this file (below)
• Commit the built code, tagging it with the version number and a brief message about the release
• Push to Github
• Run npm publish . to publish to NPM
• Run jam publish to publish to JamJS
• Autoupdate gh-pages docs
• Open a pull request to https://github.com/cdnjs/cdnjs to put the new release on the CDN

Release History

v0.1.0 - First working release with apparent compatibility with everything tested

v0.2.0 - Updated release with various tweaks and polish and real proper documentation attached

v0.3.0 - Some bugfixes (#12, #14), cookie-based log level persistence, doc tweaks, support for Bower and JamJS

v0.3.1 - Fixed incorrect text in release build banner, various other minor tweaks

v0.4.0 - Use LocalStorage for level persistence if available, compatibility improvements for IE, improved error messages, multi-environment tests

v0.5.0 - Fix for Modernizr+IE8 issues, improved setLevel error handling, support for auto-activation of desired logging when console eventually turns up in IE8

v0.6.0 - Handle logging in Safari private browsing mode (#33), fix TRACE level persistence bug (#35), plus various minor tweaks

v1.0.0 - Official stable release! Fixed a bug with localStorage in Android webviews, improved CommonJS detection, and added noConflict().

v1.1.0 - Added support for including loglevel with preprocessing and .apply() (#50), and fixed QUnit dep version which made tests potentially unstable.

License

Copyright (c) 2013 Tim Perry
Licensed under the MIT license.