Stumpy - The Kickass Logger!

Features

• Highly Configurable
• Module based Log Names
  • Different module can be given a name to make it easier to find the culprit
• Buffered Output
  • Allows you to ship the logs off to the local sawmill or whittle a cat out of them
  • Buffers are currently, per instance
• Customizable Log Format
  • Standard output across all parts of your application
• Schemas Based on Environments
• NodeJs Only (sorry browser people)
  • Groups (pretty trees O^O)
  • Colors (double rainbows!)
  • Optional All Logs Synchronise
    • Warning: current version errors are sent to stdout NOT stderr
  • All Logs with Trace Information

In the Year 3000... (Future Features)

• [/] Improve code quality
  • [ ] Create test framework
    • [ ] Spawn a process to run the tests and compare the output
    • [ ] Use examples as first set of tests
  • [x] Add code coverage (istanbul + coveralls)
  • [x] Add static analysis of code
• [ ] A String version of the Customizable Log Format
• [ ] Custom Log Type (eg. stumpy.cheese({shape:'block',color:'yellow'}))
• [ ] Customizable Log Format per Log Type
• [ ] Transports for both NodeJs and Browser
• [ ] Fix NodeJs Logs Synchronise to send output errors using stderr (small buffer?)
• [ ] Global and per instance Buffers

NPM

$ npm install stumpy

Bower

$ bower install stumpy

Even a Cat can do it

var stumpy = Stumpy();

stumpy.log("look for prey");
stumpy.info("sleep %f hours", 8.62);
stumpy.warn("kill %d mice in a day", 26);
stumpy.error("miss target");

Stumpy(options)

The first argument can be either an options Object or a name string followed by an options object. The all options have defaults.

• name - String used to when displaying a log. Default: "".
• env - String used to determine schema to use. which Default: "dev".
• replaceConsole - Boolean to enable/disable replace the console global object with Stumpy. Default: false.
• getTrace - Boolean to enable/disable capture the trace info for each log. Default: false.
• showTrace - Boolean to enable/disable display of the trace info on each log. If this is set to true, getTrace will be set to true. Default: false.
• showDateTime - Boolean to enable/disable display of the date and time on each log. Default: false if Broweser, true if NodeJS.
• showLogId - Boolean to enable/disable display of the log id. The Id's are unique for each log per session, when the browser/server restarts the Id is reset. Default: false.
• showLogType - Boolean to enable/disable display of the log type ('log', 'warn', 'error', 'info', 'trace', 'group', or 'groupEnd'). Default: false.
• syncLogs - Boolean to enable/disable display of the synchronous logs. Warning: current version errors are sent to stdout NOT stderr. Default: false.
• display - Boolean or Object. If set to true, all display options are set to true. The Object is a key:value map of all the logging types. Default: { log: true, info: true, warn: true, error: true, trace: true, group: true, groupEnd: true }
• formatFunc(log<Object>, logInstanceOptions<Object>) - The Function used to format the logs when getBuffer, onHandlers.addLog and onHandlers.delLog is called or on all log output. Default: built in function for server and browser.
• dateStringFunc(date<Date Object>) - This Function formats the data object to a string for logging. Default: built in DateString function.
• onHandlers - An Object. See Event Handler Options
• colors - An Object. See Colors Options
• group - An Object. See Group Options
• buffer - An Object. See Buffer Options
• schema - An Object. See Schema Options

Functions

• log(...) - Add/display a log. See console.log Options
• warn(...) - Add/display a warning. See console.warn Options
• error(...) - Add/display a error. See console.error Options
• info(...) - Add/display a info. See console.info Options
• trace(...) - Add/display a trace. See console.trace Options
• group([name]) - Add/display a group. Optional name (default: group).
• groupEnd([name]) - Add/display a groupEnd. Optional name (default: same name as group).
• clearBuffer() - Clears the in memory buffer.
• getBuffer() - Returns an Array of Strings after running each log thought the buffer.formatFunc. Warning browser users: getBuffer() may not return expected results unless you include the sprintf library.
• getRawBuffer() - Returns the raw buffer (Array of Objects) with all the captured data.
• printBuffer() - Prints each log in the buffer using the formatFunc.
• setEnv() - Sets the current environment and applies the schema.
• getOptions() - Returns all current options (including schema) with environment applied.
• setOptions(options) - Merges/applies options on current options, if env is set it will applied the environment schema.

Colors Options

See Cli-Color for color values The all options have defaults.

• log - String or Cli-Color Object. Default: "whiteBright"
• info - String or Cli-Color Object. Default: "blue"
• warn - String or Cli-Color Object. Default: "yellow"
• error - String or Cli-Color Object. Default: "red"
• trace - String or Cli-Color Object. Default: "magenta"
• group - String or Cli-Color Object. Default: "green"
• groupEnd - String or Cli-Color Object. Default: "green"

Group Options

Used to generate the Group Trees for NodeJS The all options have defaults.

• autoIndent - Boolean value enabling/disabling Group Trees. Default: true
• indent - Object containing the string parts used to the Group Tree for NodeJS

Buffer Options

Used to configure the buffer. The all options have defaults.

• size - Integer size of the log buffer. A 0 size will disable the buffer. When the limit is reached and a new log is add stumpy will remove the oldest log. Default: 0.
• formatFunc(log<Object>, logInstanceOptions<Object>) - The function used to format the logs when getBuffer is called. If you wish to get the unformatted buffer use getRawBuffer. Default: null.
• getTrace - Boolean to enable/disable capture of trace info on each log. Default: false.
• showTrace - Boolean to enable/disable show trace info on each log. getTrace will be set to true if this is set to true. Default: false.
• deepCopy - Boolean to enable/disable deep copy of objects stored in the buffer. The default is false to consume less memory, however objects are referenced so they could change from the original log. Default: false.

Schema Options

Used to configure the environment schemas. This is an object of environments, default: dev,stage, and prod. When an env string is set, all keys in the matching schema key are applied over all other options in the base options. The all options have defaults.

• dev - An Object for the dev environment. Default: display: { log: true, info: true, warn: true, error: true, trace: true, group: true, groupEnd: true }.
• stage - An Object for the stage environment. Default: display: { log: false, info: false, warn: true, error: true, trace: true, group: true, groupEnd: true }.
• prod - An Object for the prod environment. Default: display: { log: false, info: false, warn: false, error: true, trace: true, group: false, groupEnd: false }.

Event Handler Options

The all options have defaults of no handlers.

• addLog(logStr<String>, logObj<Object>) - A Function that will be called when a log is added. It will call the function formatting the logStr using options.formatFunc. Default: null.
• delLog(logStr<String>, logObj<Object>) - A Function that will be called when a log is deleted from the Buffer. It will call the function formatting the logStr using options.formatFunc. Default: null.
• addBuffer(logStr<String>, logObj<Object>) - A Function that will be called when a log is added. It will call the function formatting the logStr using options.buffer.formatFunc. Default: null.
• delBuffer(logStr<String>, logObj<Object>) - A Function that will be called when a log is deleted from the Buffer. It will call the function formatting the logStr using options.buffer.formatFunc. Default: null.

Examples

Browser

• Browser very simple example
• Browser example using Custom Formatting and Handlers

NodeJS

• NodeJS example using Replace Console, Sync Logs, Show Trace, Show Log Id and Show Log Type
• NodeJS example using Custom Formatting and Event Handlers

License

MIT: what else?

Full license go go go! »

Blah blah blah... Tests

Mocha

$ npm test

Karma

$ npm run-script test-browser