Balsa
Lightweight, multi-relay JavaScript logging for the browser
Balsa is a lightweight, multi-relay logging library designed for use in the
browser. It includes a relay for consistent, cross-browser JavaScript console
logging, as well as an AJAX relay to send log messages to logging servers.
Prerequisites
An environment that supports the
CommonJS module pattern (require
,
module
, exports
, etc.), e.g., Node.js, but it really
shines when bundled with Browserify and used in the
browser.
Basic Usage
// Create a new Balsa logger with a console relayvar balsa = 'balsa' relays: 'balsa/relay/console' ; // Start loggin'!balsa;balsa;balsa;balsa;balsa;
Initialization
To begin using Balsa, you must first import it with require
, and create a new
instance.
var balsa = 'balsa' ;
You may configure Balsa during instantiation as in the following example.
Please note that all configuration is optional and the following represents the default value of each optional configuration item.
var balsa = 'balsa' /** * Enable/disable logging. May be modified post-initialization via * `.enable()` and `.disable()` */ enable: true /** * Logging prefix that will be prepended to each log message, e.g., [myApp] */ prefix: null /** * Define default minimum logging level, i.e., don't log messages below the * specified level. If `null`, all levels will be logged. Possible values * are: * - null - Log ALL THE THINGS * - 'debug' - Don't log below debug (lowest level, log everything) * - 'log' - " " " log * - 'info' - " " " info * - 'warn' - " " " warn * - 'error' - " " " error * * Relays may override this value in their own configuration. */ minLevel: null /** * Define the message format. Available variables are: * * - `$TIMESTAMP` - Timestamp of the log, in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) * - `$LEVEL` - The logging level * - `$PREFIX` - The message prefix * - `$MESSAGE` - The message body * * Relays may override this value in their own configuration. */ messageFormat: '$TIMESTAMP $LEVEL\t$NAMESPACE\t$MESSAGE' /** * Add relays, e.g., * * relays: [ * new require( 'balsa/relay/console' )(), * new require( 'balsa/relay/ajax' )( { * host: 'log.example.com', * port: 1234 * } ) * ]; */ relays: ; ;
API
After initialization, you may use any of the following functions.
balsa.{debug, log, info, warning, error, etc.}( message )
Log a message at the specified level. There are 4 available levels, from most to least severe:
debug
log
info
,warning
,warn
error
,err
balsa; balsa; balsa; balsa;balsa; balsa;balsa;
balsa.enable()
Enable logging.
balsa;
balsa.disable()
Disables all logging.
balsa;
balsa.prefix( prefix )
Set the prefix that will be prepended to every log message.
// Prefix all messages with '[myApp]'balsaprefix '[myApp]' ;
balsa.minLevel( minLevel )
Sets the minimum default level message that will be logged. If 'all', all levels will be logged.
Note that relays may define their own min level, which will override this value for those relays.
// Only log warnings and below (error)balsa;
balsa.messageFormat( messageFormat )
Sets the format each message will be outputted as. Available variables are:
$TIMESTAMP
- Timestamp of the log, in ISO 8601$LEVEL
- Level of the message$PREFIX
- The message prefix$MESSAGE
- The message body
// Configures the message format, e.g.,// 2014-09-30T18:58:45+08:00, warn [myApp], Log messagebalsa;
balsa.add( relay )
Adds a new relay to the logger.
// Adds an AJAX relay with a custom level, a host, and a port.balsa;
balsa.remove( relay )
Removes a relay from the logger.
// Create a new AJAX relayvar ajaxRelay = 'balsa/relays/ajax' minLevel: 'error' endpoint: 'logs.example.com' // Add relaybalsa; // Remove relaybalsa;
Relays
Relays are where your log messages get sent to. You can attach 0 or more relays to any Balsa instance.
Relay configuration
All relays may define their own min levels, e.g., one relay may log messages of
all levels, and another may log only error
-level messages.
All relays may also define their own message formats, e.g., one relay may format its messages with a timestamp, and another relay may choose to omit the timestamp.
// Add a new console relay that logs all levels, and has a message format of// `$PREFIX: $MESSAGE`balsa;
Core relays
Balsa comes with two relays, console
and ajax
.
console
A cross-browser relay. Uses the browser's build-in JavaScript console functions
or if the console
object does not exist, the logger will fail silently to
prevent runtime errors.
balsa;
ajax
An AJAX relay. Allows you to make an AJAX call to a REST service. Two
configuration options, host
and port
are required, but type
is optional.
balsa;
Custom relays
You may also make your own relays. Use the core relays as examples, and
require
them as you would a core relay.