search

awesomeeng / awesome-log

Logging for enterprise ready nodejs applications.
MIT License
34 stars 4 forks source link

readme

npm GitHub npm GitHub contributors GitHub last commit
node GitHub issues Snyk Vulnerabilities for GitHub Repo David

AwesomeLog

AwesomeLog is a Log System for enterprise nodejs applications. It provides a basic out of the box logging solution that is ready to go with zero configuration but also gives you a highly configurable logging solution with the power to do your logging right.

Why Another Log Solution?

AwesomeLog is similar to Winston, Log, pino, Log4js, etc. and those are all good products. AwesomeLog just provides a different method of Logging; one we think is cleaner and more stable. If you want to use Winston/Log/pino/Log4js/whatever, that's perfectly fine by us. But if you want to try something a little cleaner, with a bit more features, consider AwesomeLog.

Features

AwesomeLog provides...

Contents

Installation

Couldn't be easier.

npm install --save @awesomeeng/awesome-log

Setup

It is best if you configure AwesomeLog at the top of your application. We recommened you do this immediately near the top of your main node entry point.

Setup has three steps:

1). Require AwesomeLog...

const Log = require("@awesomeeng/awesome-log");

2). Configure AwesomeLog...

// for out of the box, zero configuration
Log.init();

// or for more control
Log.init({
    // configuration options go here
});

3). Start AwesomeLog...

Log.start();

That's it. AwesomeLog is running and you can now use in any part of your application:

Usage

To use AwesomeLog once it is configured and started is simple:

1). You need to require AwesomeLog in any file/class that would reference it.

const Log = require("@awesomeeng/awesome-log");

2). Then you just log stuff out.

Log.info("message",a,b,c);

Simple.

You'll notice that Log calls take one or more arguments:

Log Levels

AwesomeLog starts with five basic Log Levels: ACCESS, ERROR, WARN, INFO, DEBUG by default). Each of these associated methods on the Log instance to allow you to easily use them. So for the default levels you get

Log.access(...)
Log.error(...)
Log.warn(...)
Log.info(...)
Log.debug(...)

If you customize the log levels, AwesomeLog will remove the default log level methods (Log.warn() etc) and replace them with methods that have your log levels names:

Log.init({
    levels: "silly,goofy,funny,bad"
});
Log.start()
Log.silly(...);
Log.goofy(...);
Log.funny(...);
Log.bad(...);

You may have as many Log Levels as you desire, but each must have a unique name. Also, there are a handful of reserved words (anything that is already in the AwesomeLog class) and you cannot use them. These include: AbstractLogWriter, AbstractLogFormatter, initialized, running, config, history, historySizeLimit, levels, levelNames, definedWriters, definedFormatters, defineWriter, defineFormatter, init, start, stop, pause, resume, clearHistory, getLevel, log, captureSubProcess, releaseSubProcess.

In addition to the log level methods, you also use the Log.log() method which takes the level as the first argument, so you can programmatically set the level if needed.

Log.log("level","message");

Log Writers

A Log Writer is the channel by which a log message is written to some output device. Writers are used to send the message to the console, the file system, a database, wherever you need your logs to end up.

AwesomeLog ships with three built-in Log Writers:

By default AwesomeLog is configured to use the Console writer only. You can change the writers during your Log.init() call if you so desire. Here's an example:

Log.init({
    writers: [{
        name: "MyConsoleWriter",
        type: "console",
        formatter: "default",
        options: {
            colorize: true
        }
    },{
        name: "MyFileWriter",
        type: "file",
        formatter: "json",
        options: {
            housekeeping: "2 hours",
            filename: "logs/MyLogs.{YYYYMMDD}.log"
        }
    }],
});

This example enables two writers, a console writer and a file writer.

You can read more about Configuration, Console Writer, or File Writer, or how to write your own Custom Log Writer in the respective documentation.

Each LogWriter is run in its own isolated process and log messages are passed to it. This allows AwesomeLog to execute much faster.

Log Formatters

A Log Formatter takes the log message details (as well as a number of other system information details) and formats that into a single string message. Each Log Writer (see above) can have it's own Log Formatter. If you do not provide a formatter, default is used.

AwesomeLog ships with four built-in Log Formatters:

You can read more about how to write your own Custom Log Formatter in the documentation.

Fields

AwesomeLog supplies a variety of field options. During configuration you can specify which fields you want to be in each log entry, although what gets output is also determined by the log formatter you choose. For example, you can specify the hostname field, but the Default formatter doesnt use it. Some formatters do output the entire log entry structure though like the CSV Formatter, the JSON formatter, or the JS Object formatter.

It is worth noting that some fields are more expensive than others, performance wise. In particular, the system field if very expensive from a performance point of view. If performance is a consideration for you, please consider leaving this field out.

Fields are configured thus:

Log.init({
    fields: "timestamp,pid,system,text,args"
});

The fields configuration property is a comma delimited string of each field name. Order is irrelevant as the formatter you choose will dictate its own ordering.

The default fields are timestamp,pid,system,text,args. If your NODE_ENV environment variable is set to prod or production the default fields will omit system to encourage better performance on production environments.

The following fields are available:

Performance

AwesomeLog is configured by default to perform in manner best suited to development. For production systems, a slioghtly more nuanced configuration will perform better, but at a reduction in development information. When run with this performance configuration AwesomeLog will perform slightly better than most other nodejs logging systems like Winston, Bunyan, Bole, Debug, etc. and performs about the same as pino.

Recommended production configuration

Log.init({
    fields: "timestamp,level,pid,text,args",
    separate: true,
    buffering: true,
    history: false
});

With regards to the fields configuration property: most fields are fine, however, the system field does add a significant performance cost and should only be used in development environments.

Documentation

Examples

AwesomeLog ships with a set of examples for your reference.

The Awesome Engineering Company

AwesomeLog is written and maintained by The Awesome Engineering Company. We belive in building clean, configurable, creative software for engineers and architects and customers.

To learn more about The Awesome Engineering Company and our suite of products, visit us on the web at https://awesomeeng.com.

Support and Help

This product is maintained and supported by The Awesome Engineering Company. For support please file an issue or contact us via our Webiste at https://awesomeeng.com. We will do our best to respond to you in a timely fashion.

License

AwesomeLog is released under the MIT License. Please read the LICENSE file for details.