log-tree

#Generate logs in hierarchical tree structure

##Philosophy

• Structure of logs should based on the flow of logic, not the time the log was generated
• Importance of logs should be determined by the end results achieved, not by arbitrary "log levels"
• Capturing of logs should be deliberate and selective, not rsysloged giant generic flat files

##Features

• Use promises or nested functions to generate logs in tree structure
• Automatically records execution time to find slow code
• Automatically log errors thrown and promises rejected
• Full log tree attached to any errors thrown to help with debugging
• Single file, no external dependencies
• TODO: Test browser compatibility

##How to use

• Perform logging using logger.log()
• Set additional properties after inital logging with logger.set()
• Return logger._root.traceId to the user
• Save logger._root.toAcyclicJSON() into a database

##API

//Creates a new logger. All child loggers will reference this logger in its `_root` property.
//options:
//    onLog: called when the log function is called on this or any of its child loggers
//    onError: called when error is thrown or promise rejected in this or any of its child loggers
new TreeLog(options) -> logger

//Adds a new child to logger. The `result` property is set to the object / return value
logger.log(message) -> null  
logger.log(message, object) -> object
logger.log(message, object, property_name) -> object[property_name]()
logger.log(message, object, property_name, [param_array]) -> object[property_name](param_array...)

//Adds a new child to logger. `func` is called with the new child logger as first parameter
logger.log(message, func) -> func()

//clones value and set it to logger
logger.set(key, value) -> value

//Sets the `result` property. Also updates `elapsedMS` with the time elapsed since logger is created
logger.done(result)

//Returns object with all properties with names beginning with _ stripped out.
logger.toJSON() -> object

//Returns cloned object with all properties with names beginning with _ stripped
//out and all cyclic references converted to string representation.
logger.toJSON() -> object

//Returns string representation of log.
logger.stringify(replacer, spaces)

##Example in CoffeeScript

LogTree = require 'log-tree'
Promise = require 'bluebird'
options =
    onLog: (log)-> console.log "[#{log.timestamp}] LOG: #{log.message}"
    onError: (log)-> console.log "[#{log.timestamp}] ERR: #{log.message}\n#{log.stack}"

logger = new LogTree('Example', options)

logger.log 'Logging simple objects', process.versions

logger.log 'Nested logging', (logger) ->
    logger.log 'Child log 1', (logger) ->
        return 'Return value is logged'
    logger.log 'Child log 2', (logger, done) ->
        done 'Callback value is logged'
        return 'Return value is ignored'

try
    logger.log 'Logging with error thrown', (logger) ->
        throw new Error('Error message')
catch err
    #the full log can be found at err.logTree
    #also, the error thrown is attached to the log

logger.log 'Logging with promises', (logger) ->
    new Promise (resolve, reject) ->
        logger.log 'This is the promised child'
        setImmediate ()->
            resolve 'The resolved value is captured'
        return null
.then () ->
    logger.log 'This is chained after the previous promise'
    console.log 'This is the final tree structure generated'
    console.log JSON.stringify logger._root, false, 4