npm package: @horanet/hlog
Description: Plug-and-play log management for Express-based web applications
Author: Horanet
Latest version: 0.0.3

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

## Introduction

Module `hlog` is a wrapper around [winston](https://www.npmjs.com/package/winston) and [morgan](https://www.npmjs.com/package/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](https://en.wikipedia.org/wiki/Syslog) 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:

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

Then define a config object containing configuration. All parameters are optional. Refer to [Config Parameters](#config-parameters) section for details. For example:

```js
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`:

```js
hlog(config, app);
```

Where `app` is an instance of server powered by [express](https://www.npmjs.com/package/express):

```js
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

```shell
npm install @horanet/hlog
```

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

```shell
npm install
npm run example
```