README

hlog: plug-and-play log management for express-based web applications

Introduction

Module hlog is a wrapper around winston and morgan. Although these modules are powerful, hlog is intended to provide a logging function with much simpler interface, but universal and ready for everyday logging purpose (including error log and access log).

Features

Highly configurable. Most frequently used parameters for logging services are included:
- Log storage location
- Log rotation: log files can be compressed, archived, renamed or delete after a predefined time
- Log level: keep only log message with priority (severity) equal to or higher than this level
- Toggle printing to standard output: besides sending log messages to log file, messages passed to console.* functions can be configured to be printed to node server standard output or not

Error Logs

Functional logging: different logging severity levels to log application's output, conforming to the standard keywords: [log, debug, info, warn, error]
console.* functions (where * can be either debug, http, info, warn, error, or log- which is equivalent to console.debug) are overridden: messasages sent to console.* are written to log files, with corresponding timestamp and log level.

Access Logs

http keyword is reserved for HTTP access logging
Username of each request with successful authentication

Usage

First require the module:

const hlog = require('@horanet/hlog');

Then define a config object containing configuration. All parameters are optional. Refer to Config Parameters section for details. For example:

const config = {
  // Refer to the README file for the description of the params
  dir: './logs',
  retentionPeriod: '15d',
  loglevel: 'info',
  debug: true,
  remoteUser: (req) => 'john.doe'
};

Then pass the configurations to hlog:

hlog(config, app);

Where app is an instance of server powered by express:

const express = require('express');
const app = express();

The module is ready for use. One can use console.* to log as usual, all the logging messages will either be suppressed in the console and goes directly to the log file instead (and still can be monitored in real time by, e.g., tail -f), or they goes to both the standard output and the log files (if the debug option in config is set to true).

A minimal working example of an express-based server that uses hlog is found in ./example/index.js.

Config Parameters

dir [optional] (default is './logs'): log storage location, both absolute and relative paths are supported.
retentionPeriod [optional] (default is 15d for 15 days): time to keep the log files (log files older than this retentionPeriod are deleted).
loglevel [optional] (default value is warn): logs with this level or above are saved into error log file; logs with a lower level are dropped.
remoteUser [optional]: function to get request authenticated username, which is stored into access log as remote-user. If undefined, req.user.login information in the request access is looked for.
debug [optional]: if set to true true, messages passed to console.* functions are also printed into node server standard output besides being saved in error log file.

Install and Example

To install the package

npm install @horanet/hlog

To run the example (the script located in ./example/index.js):

npm install
npm run example

Usage no npm install needed!