Blackbird - Open Source JavaScript Logging Utility

Demos

Output all message types

Generate test string

Setup

Adding Blackbird to your page

Download the files and place them on your server or in a local directory on your computer.
Include blackbird.js in your page.
Inlcude blackbird.css in your page.

Your HTML source should look similar to the following code:

Browser compatibility

Blackbird is has been smoke-tested on the following browsers:

Internet Explorer 6+
Firefox 2+
Safari 2+
Opera 9.5

Usage

Public API

log.toggle(): Hide/show Blackbird
log.move(): Move Blackbird to next fixed positions: top-left, top-right, bottom-left, bottom-right
log.resize(): Expand/contract Blackbird
log.clear(): Clear all contents of Blackbird
log.debug( message ): Add a debug message to Blackbird; message: the string content of the debug message
log.info( message ): Add an info message to Blackbird; message: the string content of the info message
log.warn( message ): Add a warning message to Blackbird; message: the string content of the warn message
log.error( message ): Add an error message to Blackbird; message: the string content of the warn message
log.profile( label ): Start/end a time profiler for Blackbird. If a profiler named string does not exist, create a new profiler. Otherwise, stop the profiler string and display the time elapsed (in ms).; label: the string identifying a specific profile timer

Keyboard controls

Hide/show: F2
Move: Shift + F2
Clear: Alt + Shift + F2

Interface controls

Pressing the Alt key while clicking any message filter control will only show messages of that type. For example, Alt + click to show only debug messages.

Bookmarklets

Drag the following links to your bookmarks toolbar for quick access to Blackbird commands:

clear
move
resize
toggle

Customization

Changing the namespace

The default configuration attaches the public API for Blackbird to the global variable log. It is possible to have conflicts with existing variable declarations, and it is possible to redefine the global variable log in other blocks of JavaScript. If you want to define a different variable for Blackbird, such as blackbird, replace the assignment for NAMESPACE with any other string.

var NAMESPACE = 'log';

can be replaced with:

var NAMESPACE = 'blackbird';

or:

var NAMESPACE = 'myCustomLog';

The global API will be affected by this change. If you choose to replace log with myCustomLog, then log.debug will become myCustomLog.debug.

Capture & cancel logging statements

If you're shipping code with logging statements, you might want to capture and cancel commands intended for Blackbird. The following code will do this:

About

Credits

The code (blackbird.js, blackbird.css) and image assets (blackbird_panel.png, blackbird_icons.png) were created by G. Scott Olson.

The concept for Blackbird was sparked by JavaScript Logging, an article by David F. Miller. The first iteration of this project, named jsLogger, was developed for internal use at Orbitz. In the fall of 2007, jsLogger was rewritten from the ground up, given a facelift, and named project Blackbird.

Contributing to the Blackbird Project

Blackbird is an open source project. If you're intereted in contributing, you can start by checking out the project page on Google Code.