README.md

Huzzah

You can finally say - Huzzah!!!

It is one of the fastest and dead simple hierarchical text logger.

Let step by step explain what does it mean.

One of fastests

$ node benchmark/json.js
huzzah-fast-time.info json format x 988,555 ops/sec ±0.92% (89 runs sampled)
huzzah.info json format x 482,806 ops/sec ±2.96% (82 runs sampled)
huzzah.info empty x 1,468,626 ops/sec ±1.66% (85 runs sampled)
huzzah.info no format x 1,612,675 ops/sec ±1.43% (85 runs sampled)
bunyan.info x 281,758 ops/sec ±2.04% (85 runs sampled)
pino.info x 735,848 ops/sec ±0.72% (93 runs sampled)
pino-fast-time.info x 1,217,475 ops/sec ±1.10% (88 runs sampled)

$ node benchmark/logging.js
huzzah.info text format x 953,088 ops/sec ±0.96% (89 runs sampled)
huzzah.info json format x 548,774 ops/sec ±0.97% (90 runs sampled)
huzzah.info raw logger x 1,840,130 ops/sec ±0.76% (90 runs sampled)
winston.info x 68,487 ops/sec ±16.17% (56 runs sampled)
intel.info x 141,388 ops/sec ±4.93% (76 runs sampled)
bunyan.info x 209,748 ops/sec ±3.09% (66 runs sampled)
log4js.info x 636,488 ops/sec ±1.52% (81 runs sampled)
pino.info x 424,048 ops/sec ±2.76% (83 runs sampled)
(node:672) (pino) `slowtime` is deprecated: use `timestamp: pino.stdTimeFunctions.slowTime`

Dead simple

In usage:

var logger = require("huzzah").get("some_logger");

logger.trace("Some error can happen %s", "argument");

But we still need some configuration what and where to output:

var ConsoleHandler = require("huzzah/handlers").ConsoleHandler;

// require("huzzah") returns default logger factory instance
// which contains loggers and their settings
require("huzzah")
  // get settings of logger with name 'root'
  .settings("root") // see hierarchical section about what root mean (it is parent of all loggers)
  // output every log message to console, from all loggers (.addHandler call can be chained)
  .addHandler(new ConsoleHandler());

Hierarchical loggers

All loggers have string names. We can create chain of loggers by separating its name with dots. For example if we have logger with name a.b.c than its parents will be a.b, a and root.

That means you can configure some parent loggers and all nested loggers will reuse thier settings. In simple case you can configure only root logger as single configuration point.

How to use

1. Install

   npm install --save huzzah
   

2. Configure

   var huzzah = require("huzzah");
   
   // get settings of some loggers
   var settingsOfRootLogger = huzzah.settings("root");
   
   settingsOfRootLogger
     // let add console handler
     .addHandler(new ConsoleHandler())
     // let add output to file
     .addHandler(new StreamHandler().setStream(fs.createWriteStream("debug.log")));

   See API.md for more info.

3. Use

   var logger = require("huzzah").get("some_logger");
   
   logger.error("Some error happen", err);

FAQ

1. I need logger to reject all records with log level < INFO.

   // settings it is LoggerSettings (what is returned by LoggerFactory#settings)
   settings.setLevel("INFO");

2. I want my own format of records

   handler.setFormat("%date %msg%n");

3. I want to produce JSON

   var jsonFormat = require("huzzah/json-format");
   handler.setFormat(jsonFormat());
   
   //jsonFormat can accept bunyan style serializers

4. I want to add more fields to record (for JSON output)

   logger.with({ req, res }).info("Some message");

   With such way you can use it with express like:

   app.use((req, res, next) => {
     req.logger = logger.with({ req, res, req_id: uuid() });
   });
   

   And use req.logger to output additional context information.

license

MIT