Simple sub-process logging for Node.Js with lots of config options.

Contents

• Introduction
• Getting Started
• Documentation
• Dependencies
• License
• Author

Introduction

Billabong - Built by @elliotgibson for @content-dynamics.

This project was created to provide a simple lightweight, and subprocessed highly customizable logging interface for Node projects. It uses Classes which can be extended to provide more customization if required.

A sample of the customization options:

• Branches : A "branch" is a seperate category within the logger, each branch can be setup with different destinations.

• Channels: A "channel" is simply a means of categorizing logging messages within each branch.

• Destinations: A "destination" is a reference to where you want the logging messages to be stored. Each destination supports filtering and transformations.

• Filter: A "filter" is used to filter messages into the destination, filters can be set-up to filter any of the options or even certain messages.

• Translator: A translator is used to "translate" filtered messages into a certain format ready to be saved to the destination.

Getting Started

To install simply run npm install billabong in your project.

To use the Logger simply require and initalize the logger:

const Billabong = require('billabong');

//Creates a localy scoped connection to the Logger.
const logger = new Billabong();

//Creates a localy scoped connection to the Logger.
const logger = Billabong.Local();

logger.Log('Message') //this works

/*---------------------------------------------*/

//Creates a globally scoped connection to the logger available through bbng
Billabong.Global()

bbng.Log('Message') //this works in any file used in your application (available through "bbng")

//Also creates a globally scoped connection, however is named: Billa
Billabong.Global('Billa')

Billa.log('Message') //this also works in any file (available through "Billa" )

The above code will create a connection to the sub-process logger using the default configuration - as you can see the Logger connection can be locally, or globally scoped - we recommend keeping the Logger locally scoped and requiring a single instantiation file.

The base logger has 4 base "channels" or Log types:

Logger.Log(message, { options })

Logger.Log("By default this won't be logged to console or to the logging file");

Logger.Log("This will ensure that the info is logged to console and to the logging file",{ important: true });

Logger.Log("This will add a debug stack to the logging message and write it to the logging file and console",{ important:true, debug: true });

Logger.Info(message, { options })

Logger.Info("This will simply show as info in the log!");

Logger.Info("This will ensure that the info is logged to console",{ important: true });

Logger.Info("Thiswill add a debug stack to the warn message",{ debug: true });

Logger.Warn(message, { options })

Logger.Warn("This will simply show as a warning in the log!");

Logger.Warn("This will ensure that the warning is logged to console",{ important: true });

Logger.Warn("This won't add a stack to the warn message",{ debug: false });

Logger.Error(message, { options })

Logger.Error("This will simply show as an error in the log!");

Logger.Error("This will set the debug message level to 50",{ level: 50 });

Logger.Error("This won't add a stack to the logged message",{ debug: false });

Advanced Configuration

To configure the logger with different configurations create a new file called def.bbng.js in your root directory. Find out more...

Ensure that it exports a function which returns an instance of the Logger.

Example

const { Logger, Branch, Channel, Destination } = require('billabong')

module.exports = ()=> {

    const dest = Destination(console.log)
    const branch = new Branch('default', { destinations: [ dest ]});

    const Logger = Logger(Branch);
    return Logger;
}

Documentation

Full documentation for setup and development using the logger is available here: billabong/documentation

Dependencies

Chalk - Used to make console logging fun! Used by the Translator class.

@node/child-process - Used for sub-processing on node. Used by the Logger using child_process.fork()

@node/util - Used for utilities on node. The default translator instance uses util.inspect(message_object)

@node/fs - Used to read, write and minipulate files. We use fs.createWriteStream,fs.readFileSync and fs.writeFileSync for manipulating log files generated by the logger and "worker template files" used by our subprocessing code.

@node/path - Used for anything "path" based for windows and unix systems. We use fs.resolve to translate relative paths into absolute paths in our subprocessing code.

Contributing

Contributions to the project are more than welcome! Please visit the contributions guide for more information.
Feel free to check the issues page if you want to contribute to solving issues.

If you would like to request a new feature please follow the request guide: Request a new feature

Author

:man_technologist: Elliot Gibson

GitHub: @elliotgibson
Twitter: @egibson_glass
Instagram: @egibson_glass

License

Copyright 2021 Elliot Gibson.
This project is licensed with the MIT license.